What this usually means
The error arises when a flex container (Row, Column, Flex) cannot fit its children within its allocated space. Flutter's layout engine computes constraints from parent to child, and if the total flex or non-flex children exceed the available main-axis size, the container overflows. This is not a bug in Flutter but a layout conflict: either the container lacks a scroll view, the children have fixed sizes that sum too large, or the parent constraints are too tight. The yellow/black banner only appears in debug mode; in release mode the overflow silently clips, causing a broken UI that users will notice as missing or overlapping content.
The first ten minutes — establish facts before touching code.
- 11. Replicate the overflow on a device/emulator and inspect the yellow/black banner — note the axis (horizontal/vertical) and pixel count.
- 22. Wrap the overflowing parent (Row/Column) in a SizedBox with a fixed height/width to confirm the error disappears (temporary diagnostic).
- 33. Run 'flutter run' with --debug and look for 'overflowed' in the console output; note the exact widget type and overflow direction.
- 44. Use Flutter Inspector (in Android Studio/VS Code) to select the overflowing widget — the layout explorer shows constraints and sizes.
- 55. Check if the parent has a scrollable ancestor; if not, consider adding SingleChildScrollView or ListView.
- 66. Add borders (Container decoration) to child widgets to visualize their bounds and find which child is taking unexpected space.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchlib/…/your_widget.dart — the Row/Column/Stack that triggers the overflow
- searchFlutter DevTools Inspector — 'Layout' tab shows constraint info and overflow highlights
- searchDebug console output — exact line number and overflow pixel count
- searchpubspec.yaml — if using third-party widgets that might have fixed sizes (e.g., Cupertino widgets)
- searchMaterial/Theme data — check if default padding/margins are contributing (e.g., ListTile default padding)
- searchMediaQuery.of(context).size — the screen size may be smaller than expected in landscape or split-screen
Practical causes, not theory. These are the things you will actually find.
- warningUsing Row with multiple children that have fixed widths (e.g., SizedBox, Container with width) exceeding available space
- warningColumn inside a non-scrollable parent with children having fixed heights summing more than viewport height
- warningNesting a Row inside a Column without wrapping the Row in Expanded or Flexible
- warningForgetting to wrap a ListView or GridView in an Expanded when placed inside a Column
- warningUsing EdgeInsets.all() with large values on a Row/Column children, consuming too much space
- warningText widget with overflow: TextOverflow.visible (default) causing text to push past container bounds
Concrete fix directions. Pick the one that matches your root cause.
- buildWrap the overflowing child in Expanded or Flexible to distribute space proportionally
- buildReplace Row/Column with Wrap widget to allow items to flow to the next line/column
- buildAdd scroll physics: wrap the overflowing parent in SingleChildScrollView with a scroll direction (scrollDirection: Axis.horizontal for rows)
- buildSet mainAxisSize: MainAxisSize.min on the flex container to shrink-wrap children (if overflow only happens on some screens)
- buildUse FittedBox or AspectRatio to scale content down when constraints are tight
- buildHardcode a minimum width/height using ConstrainedBox with constraints that respect the parent
A fix you cannot prove is a guess. Close the loop.
- verified1. Re-run the app in debug mode — confirm the yellow/black banner no longer appears on any screen size (test with device simulator rotation).
- verified2. Use Flutter Inspector to select the formerly overflowing widget and verify its size fits within parent constraints.
- verified3. Add an assertion: assert(!_overflowDetected) or use RenderObject.debugCheckIntrinsicSizes in a test.
- verified4. Write a widget test that renders the layout at various screen sizes (e.g., 320, 375, 414 width) and checks no overflow via 'overflowed' in debug output.
- verified5. Test on a physical device with a small screen (e.g., iPhone SE) and in landscape mode.
Things that make this bug worse or harder to find.
- warningBlindly adding Expanded to every child — this can cause layout conflicts if multiple Expanded widgets compete for zero space.
- warningUsing SizedBox with double.infinity — that causes unbounded constraints and immediate overflow.
- warningForgetting that ListView inside Column must be wrapped in Expanded (ListView needs bounded height).
- warningIgnoring the overflow in release mode — just because you don't see the banner doesn't mean the UI isn't broken.
- warningOverusing SingleChildScrollView as a band-aid — can cause nested scroll conflicts and performance issues.
- warningSetting fixed pixel values (e.g., width: 200) without considering different screen sizes — leads to brittle layouts.
The Case of the Vanishing Confirm Button
Timeline
- 09:15Deployed v2.1.0 to Play Store beta. Received crash reports from users on small phones (Galaxy S10e).
- 09:30Reproduced on Pixel 5 emulator at 360dp width. Yellow banner: 'A RenderFlex overflowed by 34 pixels on the bottom'.
- 09:45Located the widget: a Column inside a Scaffold body containing a form and a 'Confirm' button at the bottom.
- 10:00Used Flutter Inspector: the Column had unbounded height (shrinkWrap) and its children (text fields + button) exceeded the screen.
- 10:10Checked the parent: Scaffold body was just a Container with no scroll. Added SingleChildScrollView around the Column.
- 10:20Scroll worked, but the button was still cut off. Realized SingleChildScrollView didn't push the button to the bottom.
- 10:30Refactored: wrapped the Column in a Stack with Positioned bottom for the button, or used a Column with Expanded and a bottom-aligned button.
- 10:45Chose a LayoutBuilder approach: if content height + button > screen, use ListView; else use Column. Tested on multiple screen sizes.
- 11:00Wrote a widget test that verifies no overflow on 320dp and 414dp widths. Passed. Deployed hotfix.
I was a junior dev at a fintech startup, and we shipped a form screen with a 'Confirm' button at the bottom. On my iPhone 13 Pro it looked perfect. But users on Galaxy S10e reported the button was invisible. I opened the project, ran on a Pixel 5 emulator at 360dp, and immediately saw the yellow/black banner: 'A RenderFlex overflowed by 34 pixels on the bottom.' The debug console pointed me to a Column inside the Scaffold body.
I inspected the Column with Flutter Inspector: it had mainAxisSize: MainAxisSize.min (shrinkWrap) and children: three TextFields and a SizedBox button. The total height of the children was ~700dp, but the screen height was ~640dp after status bar and app bar. The Column couldn't shrink its children, so it overflowed. My first instinct was to slap a SingleChildScrollView around the Column. That made the form scrollable, but the button still disappeared because the scroll view only scrolled the content—the button wasn't anchored to the bottom.
I refactored the layout entirely. I used a LayoutBuilder to check available height. If the content height plus button exceeded the available space, I switched to a Column with an Expanded ListView for the fields and a bottom-aligned button using a Stack. I also used Flexible for text fields to let them shrink. I wrote a widget test that measured the render tree and asserted no overflow for screen widths 320 to 414. The hotfix went out within 2 hours. The lesson: never trust your own device; always test on the smallest screen you support.
Root cause
Column with shrinkWrap and fixed-height children placed in a Scaffold body with no scroll, causing bottom overflow when total child height exceeded viewport height.
The fix
Used LayoutBuilder to conditionally render a scrolling layout when content exceeds available height, with the button anchored to the bottom via Stack or bottomNavigationBar.
The lesson
Always test on the smallest screen size your app supports. Use LayoutBuilder or MediaQuery to adapt layouts, not just fixed sizes. And never assume a button is visible just because it's in the widget tree.
Flutter's layout engine works by passing constraints down the tree: a parent tells each child its maximum and minimum width/height. The child then decides its size within those constraints and reports back. The error 'overflowed by X pixels' happens when a child's size exceeds the constraints imposed by its parent. For a Row, the parent constraint on the main axis (horizontal) is the width of the Row. If the sum of children's widths plus padding exceeds that width, overflow occurs.
The key concept is 'tight' vs 'loose' constraints. A tight constraint forces a specific size (e.g., SizedBox(width: 100) gives a tight width of 100). A loose constraint allows a range (e.g., Expanded gives a loose constraint with min=0, max=available). Overflow often arises when a tight child is placed inside a flex container that doesn't have enough space to satisfy all tight constraints.
The Flutter Inspector in Android Studio/VS Code is your best friend. Open it, select the widget that shows the yellow banner. In the 'Layout' tab, you'll see the constraints passed to the widget and its actual size. The overflowed widget will have its size highlighted in red if it exceeds constraints. You can also enable 'Show paint baselines' to see the exact bounds.
Another trick: run your app with 'flutter run --profile' to disable the overflow banner but still get a performance overlay. Or add a debugPrint in the build method to log the widget's size using RenderObject's size property. But the quickest way is to use the Inspector's 'Select Widget Mode' and tap on the yellow area.
When a simple Expanded or SingleChildScrollView isn't enough, LayoutBuilder gives you programmatic control. LayoutBuilder provides the parent's constraints in its builder callback. You can then conditionally return different widgets based on available space. For example, if the available width is less than 360, use a Column with shrinkWrap and scroll; otherwise use a Row with fixed spacing.
Another pattern is to use OrientationBuilder to switch between portrait and landscape layouts. Many overflow bugs only appear in landscape because the height shrinks dramatically. By using OrientationBuilder, you can adjust the layout (e.g., switch from a vertical list to a horizontal carousel).
To catch overflow bugs before deployment, write widget tests that simulate small screens. Use TestWidgetsFlutterBinding and set the surface size via 'tester.binding.setSurfaceSize(Size(320, 568))' to mimic an iPhone SE. Then pump your widget and look for the overflow error in the console. You can also use 'expect(tester.takeException(), isNull)' to ensure no exceptions were thrown.
Flutter's test framework does not visually show the yellow banner, but the error is logged. Wrap your test in a try-catch for FlutterError or use 'debugPrint' to capture overflow messages. You can also programmatically check the render tree: find the RenderFlex and compare its size to its parent's constraints. This is more involved but gives precise pass/fail.
A frequent mistake is wrapping a Column in a SingleChildScrollView but not giving the Column a bounded height. The SingleChildScrollView itself has unbounded height (it scrolls), so the Column inside it will try to be as tall as its children, causing no overflow but also no scrolling. The proper pattern is to set the Column's mainAxisSize to MainAxisSize.min (shrinkWrap) and ensure the scroll view's child has a constraint that limits its height. Alternatively, use a ListView or CustomScrollView which handle this correctly.
Another pitfall is nesting a ListView inside a Column without Expanded. ListView needs a bounded height, but a Column gives unbounded constraints. Always wrap ListView in Expanded or SizedBox with a fixed height. The same applies to GridView, PageView, and other scrollable widgets. If you need a mix of scrollable and non-scrollable content, consider using NestedScrollView or a custom Sliver layout.
Frequently asked questions
Why does the overflow banner only appear in debug mode?
The yellow/black banner is a debug-only feature to alert developers of layout overflow. In release mode, Flutter clips the overflowing widget silently. This means users will see cut-off content without any visual indicator, making it even more important to catch these during development. You can simulate release mode overflow by running 'flutter run --release' and checking for functional issues.
Can I ignore an overflow of 1 or 2 pixels?
No. Even a single pixel overflow means your layout is not respecting constraints. It may appear fine on most devices but can cause a janky scroll or clipped content on others. Additionally, Flutter's layout engine is deterministic; a 1-pixel overflow today can become 10 pixels on a different screen density. Fix it properly with Flexible or Expanded instead of relying on clipping.
What's the difference between Expanded and Flexible?
Both Expanded and Flexible allow a child to fill available space, but Expanded forces the child to occupy all remaining space (flex: 1), while Flexible allows the child to be smaller if its intrinsic size is less. Use Expanded when you want the child to be exactly the remaining space; use Flexible when the child can shrink but not grow beyond its intrinsic size. For overflow fixes, Expanded is more common because it forces the child to fit within constraints.
I added SingleChildScrollView but the overflow still shows. What am I missing?
SingleChildScrollView only works if its child has a bounded constraint in the scroll direction. If the child (e.g., a Column) has unbounded height, the scroll view can't determine how much to scroll. You must ensure the Column's mainAxisSize is set to MainAxisSize.min (shrinkWrap) and that the scroll view's parent (e.g., the Scaffold body) gives a bounded height. Alternatively, use a ListView which inherently handles unbounded content.
How do I find the exact widget causing overflow in a complex tree?
Use the Flutter Inspector's 'Select Widget Mode' (eyedropper icon) and tap on the yellow/black area. The Inspector will highlight the overflowing RenderFlex. You can then navigate up the widget tree to see which ancestor has the constrained size. Another method: add a RenderObject to the tree and override 'paint' to draw a border around each child, then visually inspect. But the Inspector is fastest.