Flutter Errors
Testing & Qualityflutter-errorsFlutter Errors is an Agent Skill for testing & quality published in the evanca/flutter-ai-rules repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when hitting layout errors (RenderFlex overflow, unbounded constraints, RenderBox not laid out), scroll errors, or setState-during-build errors.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/evanca/flutter-ai-rules/blob/HEAD/skills/flutter-errors/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/flutter-errors, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Flutter Errors Skill
This skill provides solutions for the most common Flutter runtime and layout errors.
RenderFlex Overflowed
Error: A RenderFlex overflowed by X pixels on the right/bottom.
Cause: A Row or Column contains children that are wider/taller than the available space.
Fix: Wrap the overflowing child in Flexible or Expanded, or constrain its size:
Row(
children: [
Expanded(child: Text('Long text that might overflow')),
Icon(Icons.info),
],
)
Vertical Viewport Given Unbounded Height
Error: Vertical viewport was given unbounded height.
Cause: A ListView (or other scrollable) is placed inside a Column without a bounded height.
Fix: Wrap the ListView in Expanded or give it a fixed height with SizedBox:
Column(
children: [
Text('Header'),
Expanded(
child: ListView(children: [...]),
),
],
)
InputDecorator Cannot Have Unbounded Width
Error: An InputDecorator...cannot have an unbounded width.
Cause: A TextField or similar widget is placed in a context without width constraints.
Fix: Wrap it in Expanded, SizedBox, or any parent that provides width constraints:
Row(
children: [
Expanded(child: TextField()),
],
)
setState Called During Build
Error: setState() or markNeedsBuild() called during build.
Cause: setState or showDialog is called directly inside the build method.
Fix: Trigger state changes in response to user actions, or defer to after the frame using addPostFrameCallback:
@override
void initState() {
super.initState();
WidgetsBinding.instance.addPostFrameCallback((_) {
// Safe to call setState or showDialog here
});
}
ScrollController Attached to Multiple Scroll Views
Error: The ScrollController is attached to multiple scroll views.
Cause: A single ScrollController instance is shared across more than one scrollable widget simultaneously.
Fix: Ensure each scrollable widget has its own dedicated ScrollController instance.
RenderBox Was Not Laid Out
Error: RenderBox was not laid out: ...
Cause: A widget is missing or has unbounded constraints — commonly ListView or Column without proper size constraints.
Fix: Review your widget tree for missing constraints. Common patterns:
- Wrap
ListViewinExpandedinside aColumn. - Give widgets an explicit
widthorheightviaSizedBoxorConstrainedBox.
Debugging Layout Issues
- Use the Flutter Inspector (in DevTools) to visualize widget constraints.
- Enable "Show guidelines" to see layout boundaries.
- Add
debugPaintSizeEnabled = true;temporarily in yourmain()to paint layout bounds. - Refer to the Flutter constraints documentation for a deeper understanding of how constraints propagate.