Debug FlutterFlow UI problems using the Widget Tree panel to inspect the widget hierarchy, Debug Paint mode to visualise widget boundaries and padding, the overflow error indicator (yellow-black stripes) to identify clipped content, and the device preview selector to test different screen sizes. These tools resolve the vast majority of layout issues without exporting code.
Systematic UI Debugging in FlutterFlow
Layout bugs in FlutterFlow usually fall into three categories: overflow errors where content is wider or taller than its container, invisible widgets that are hidden by incorrect conditional logic or zero opacity, and responsive issues where the layout looks correct on one device size but breaks on another. FlutterFlow provides several built-in debugging tools that let you diagnose all three categories directly in the visual editor without needing to export code or run the Flutter inspector. This tutorial covers each tool and when to use it, so you can fix UI bugs in minutes rather than hours.
Prerequisites
- A FlutterFlow project with at least one page showing a UI issue
- Basic familiarity with the FlutterFlow editor canvas and Properties panel
- No coding experience required — all debugging tools are in the FlutterFlow UI
Step-by-step guide
Use the Widget Tree panel to locate the problem widget
Use the Widget Tree panel to locate the problem widget
Click the Widget Tree icon in the left sidebar (it looks like a branching hierarchy). The Widget Tree shows every widget on the current page in a collapsible tree structure that mirrors the actual Flutter widget hierarchy. When you have a UI bug — a missing widget, unexpected spacing, or a layout that looks wrong — click through the tree to find the widget in question. Each item in the tree is clickable, and clicking one selects and highlights it on the canvas with a blue outline. This is far faster than clicking on the canvas and accidentally selecting a parent container. Use the search box at the top of the Widget Tree to find a widget by type name when the tree is deeply nested.
Expected result: You can select any widget on the page directly from the Widget Tree and see its properties in the right-hand Properties Panel.
Enable Debug Paint to visualise widget boundaries
Enable Debug Paint to visualise widget boundaries
Run your app in FlutterFlow's built-in preview by clicking the Preview button (the play icon in the top bar). Once the preview is running, look for the debug toolbar that appears below the preview window. Click the paintbrush icon to enable Debug Paint mode. Debug Paint draws coloured outlines around every widget: blue for general widgets, orange for padding, yellow for spacing. This makes invisible spacing immediately visible — a widget that appears to have no margin may actually have a large Padding widget wrapping it. Debug Paint also shows baseline alignment guides for text widgets, which helps diagnose text that appears vertically misaligned inside a Row.
Expected result: The preview shows coloured borders around every widget, making padding, margins, and widget boundaries visible as distinct coloured regions.
Read and fix overflow errors (yellow-black stripes)
Read and fix overflow errors (yellow-black stripes)
An overflow error appears as a yellow-and-black striped bar on the edge of a widget in the preview. It means a child widget is larger than its parent allows. The stripe indicates the direction of the overflow — a stripe on the right edge means the content is too wide, a stripe on the bottom means it is too tall. To fix an overflow: first, select the overflowing widget in the Widget Tree and check its width and height settings in the Properties Panel. If the widget has a fixed pixel size, consider changing it to Infinity (fill available space) or Wrap Content. If the parent is a Row and contains too many items, consider replacing the Row with a Wrap widget that flows items to the next line. Only use SingleChildScrollView when the content is genuinely meant to scroll — not as a quick fix for every overflow.
Expected result: After fixing the widget sizing, the yellow-black stripes disappear and the content displays correctly within its container.
Use the device preview selector to test multiple screen sizes
Use the device preview selector to test multiple screen sizes
In the FlutterFlow editor, the canvas has a device selector dropdown at the top — it shows the current device size (e.g., iPhone 14, Pixel 7). Click this dropdown to switch between a range of device presets. Test your layout on at least: a small phone (iPhone SE, 375pt wide), a standard phone (iPhone 14, 390pt), a large phone (Pixel 7 Pro, 412pt), and a tablet (iPad, 768pt+). Many overflow bugs only appear on the smallest device sizes. When you find a layout that breaks on small screens, select the problem widget and check if any widths are set to fixed pixel values — replace these with percentage-based or flexible sizing using the Expanded and Flexible widgets.
Expected result: Your layout renders correctly across all device sizes with no overflow errors or clipped content on small phones.
Debug invisible widgets with the Properties Panel
Debug invisible widgets with the Properties Panel
If a widget appears to be missing from the canvas despite being in the Widget Tree, the cause is usually one of four things: Opacity set to 0, Visibility set to false, a conditional expression that evaluates to false, or the widget positioned outside the visible bounds. To diagnose: select the widget in the Widget Tree and check the Properties Panel. Look for an Opacity field set to 0 or a Visible When condition. For conditional visibility, click the condition expression to see what it evaluates to — click the debug icon next to the condition to test it with sample data. For off-screen positioning, check if the widget is inside an Align or Positioned widget with coordinates that push it outside the screen.
Expected result: You can identify why any widget is not visible and correct the opacity, visibility condition, or positioning that is hiding it.
Complete working example
1// Custom Widget: DebugLayoutHelper2// Use during development to visualise widget constraints3// Remove before publishing your app4// Add this as a Custom Widget in FlutterFlow and wrap any5// widget you want to inspect67import 'package:flutter/material.dart';89class DebugLayoutHelper extends StatelessWidget {10 final Widget child;11 final Color outlineColor;12 final bool showSize;1314 const DebugLayoutHelper({15 Key? key,16 required this.child,17 this.outlineColor = Colors.red,18 this.showSize = true,19 }) : super(key: key);2021 @override22 Widget build(BuildContext context) {23 return LayoutBuilder(24 builder: (context, constraints) {25 return Stack(26 children: [27 Container(28 decoration: BoxDecoration(29 border: Border.all(color: outlineColor, width: 1.5),30 ),31 child: child,32 ),33 if (showSize)34 Positioned(35 top: 2,36 left: 2,37 child: Container(38 color: outlineColor.withOpacity(0.8),39 padding: const EdgeInsets.symmetric(horizontal: 4, vertical: 2),40 child: Text(41 '${constraints.maxWidth.toStringAsFixed(0)} x '42 '${constraints.maxHeight == double.infinity ? 'inf' : constraints.maxHeight.toStringAsFixed(0)}',43 style: const TextStyle(44 color: Colors.white,45 fontSize: 9,46 fontWeight: FontWeight.bold,47 ),48 ),49 ),50 ),51 ],52 );53 },54 );55 }56}Common mistakes when debugging Your FlutterFlow App's UI
Why it's a problem: Wrapping every overflowing widget in SingleChildScrollView without understanding the root cause
How to avoid: Identify why the widget is overflowing by checking the Widget Tree and Properties Panel. Most Row overflows are fixed by wrapping child Text widgets in Expanded. Most Column overflows are fixed by using Flexible sizing or reducing fixed height values.
Why it's a problem: Clicking the canvas to select a widget and accidentally selecting the wrong parent container
How to avoid: Use the Widget Tree panel to select the exact widget you want. Type the widget name in the tree's search box to jump directly to it. This is faster and more precise than clicking the canvas for nested widgets.
Why it's a problem: Only testing the layout on one device size (usually the default iPhone 14)
How to avoid: Test on at least three device sizes before publishing: iPhone SE (smallest supported), your target device, and an iPad. Use FlutterFlow's device selector to switch between them in under 30 seconds.
Best practices
- Always use the Widget Tree panel to select deeply nested widgets — never rely solely on clicking the canvas
- Test on iPhone SE (375pt width) as your minimum baseline — it is still a widely used device size
- Use Expanded and Flexible instead of fixed pixel widths inside Row widgets to prevent overflow errors
- Enable Debug Paint mode whenever you encounter unexpected spacing or alignment — it makes invisible padding visible instantly
- Set temporary bright background colours on mystery widgets to make them visible during debugging
- Remove all DebugLayoutHelper and debug paint configurations before publishing your app
- Check conditional visibility logic with explicit test data values using the condition debug tool in the Properties Panel
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
In my FlutterFlow app I have a Row widget with three Text widgets inside it. On small phones (iPhone SE, 375pt width) I get a yellow-black overflow stripe on the right side. What is the correct way to fix this without making the row scroll horizontally?
In my FlutterFlow app, a widget is not showing on screen even though it is in the Widget Tree. It has no opacity or visibility condition set. What are all the possible reasons a widget in FlutterFlow can be invisible or off-screen, and how do I check each one using the FlutterFlow editor?
Frequently asked questions
Where is Debug Paint mode in FlutterFlow?
Debug Paint is available in FlutterFlow's built-in preview and Test Mode. Run the preview by clicking the play button in the top bar, then look for the debug toolbar below the preview window. The paintbrush icon toggles Debug Paint. It is not available in the editor canvas view — you must run the preview to access it.
Why does my layout look correct in the FlutterFlow editor but broken on my phone?
The FlutterFlow editor canvas renders a simplified approximation of your layout, not a real Flutter render. Real rendering uses the device's actual screen dimensions, pixel density, and font rendering engine. Always run Test Mode or an exported build on a real device to verify your layout — especially for complex Row/Column nesting.
How do I debug a widget that only overflows on specific device sizes?
Use the device selector dropdown in the FlutterFlow editor to switch to the problematic screen size. This renders the layout at that device's dimensions in the editor. Then use the Widget Tree to select the overflowing widget and check if any widths or heights are set to fixed pixel values that are too large for the smaller screen.
Can I use Flutter DevTools with a FlutterFlow project?
Yes, if you export your FlutterFlow project to Flutter code (requires Pro plan) and run it locally with flutter run. Flutter DevTools provides the full Widget Inspector, performance profiler, and memory viewer. For visual layout debugging without code export, FlutterFlow's built-in Debug Paint covers the most common cases.
What causes the 'A RenderFlex overflowed by X pixels' error in a FlutterFlow app?
This error means a Row or Column's children are collectively wider or taller than the available space. The most common cause is a Text widget inside a Row without an Expanded wrapper — the text wants to be as wide as its content, which can exceed the row's width. Fix it by wrapping the Text in an Expanded widget, or by giving the Row a finite width constraint.
How do I debug a Firestore query that returns data but nothing shows in the ListView?
This is a data binding issue rather than a layout bug. Select the ListView in the Widget Tree and check the Backend Query panel in the Properties Panel. Verify the collection path is correct, the query filter is not accidentally excluding all results, and the item widget is bound to the correct document fields. Use FlutterFlow's query tester to run the query and inspect the returned documents before binding them to the UI.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation