# How to Troubleshoot Common Flutter Layout Debugging Scenarios: Complete Guide

> Troubleshoot common Flutter layout debugging scenarios. Understand constraint contracts, apply Expanded or Flexible widgets, and follow a five-step workflow from the flutter skills repository for quick resolutions.

- Repository: [Flutter/skills](https://github.com/flutter/skills)
- Tags: how-to-guide
- Published: 2026-05-09

---

**Flutter layout errors stem from violating the framework's constraint contract where constraints flow down and sizes flow up, which you can resolve by wrapping widgets in `Expanded` or `Flexible` and following the systematic five-step debugging workflow documented in the `flutter/skills` repository.**

Flutter's layout engine operates on a strict contract: **constraints flow down**, **sizes flow up**, and the **parent decides the position**. When this contract breaks, you encounter runtime exceptions such as "RenderFlex overflowed" or "Vertical viewport was given unbounded height". The `flutter/skills` repository provides the **Flutter Fix Layout Issues** skill at [`skills/flutter-fix-layout-issues/SKILL.md`](https://github.com/flutter/skills/blob/main/skills/flutter-fix-layout-issues/SKILL.md), which catalogs diagnostic signatures and resolution workflows for these common violations.

## Understanding Flutter's Layout Constraint Model

The foundation of every Flutter layout debugging session rests on the three-part constraint contract implemented in the framework's rendering layer. Parents pass **constraints** downward to children, children report their **sizes** back upward, and parents ultimately decide the **position** of each child. When a widget receives unbounded constraints in a direction where it requires bounded constraints—such as a `ListView` inside a `Column`—the framework throws an exception because the layout becomes mathematically undefined. Ensuring that `ParentDataWidget`s such as `Expanded` or `Positioned` are placed directly under their required ancestors maintains the integrity of the layout tree.

## Common Layout Error Signatures

According to the **Constraint Violation Diagnostics** section in [`skills/flutter-fix-layout-issues/SKILL.md`](https://github.com/flutter/skills/blob/main/skills/flutter-fix-layout-issues/SKILL.md), three error signatures account for the majority of layout debugging scenarios.

### Vertical Viewport Unbounded Height

This error occurs when a scrollable widget like `ListView` is placed inside a `Column` without height constraints. The `Column` passes unbounded maximum height constraints downward, but `ListView` requires bounded height to determine which children to render, causing the framework to reject the layout.

### InputDecorator Unbounded Width

When a `TextField` or `InputDecorator` resides directly inside a `Row` without width constraints, the `Row` provides unbounded horizontal constraints. Since input fields attempt to expand to fill available width, the conflict generates an immediate runtime exception stating that the decorator cannot have unbounded width.

### RenderFlex Overflow

The "RenderFlex overflowed by X pixels" error appears when the combined width of children in a `Row` (or height in a `Column`) exceeds the available space. Unlike unbounded constraint errors, this represents a bounded overflow where the parent allocated finite space but children collectively demanded more.

## The Layout Error Resolution Workflow

The `flutter/skills` repository defines a precise five-step workflow in the **Layout Error Resolution Workflow** section of [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) for resolving these issues:

1. Run the application in **debug mode** and capture the exact exception string printed to the console.
2. Identify the **primary** error message, ignoring cascading "RenderBox was not laid out" secondary notes.
3. Apply the conditional fix that matches the identified error signature (e.g., wrap a `ListView` in `Expanded` for unbounded height).
4. Perform a **hot reload** to verify the fix instantly.
5. If new layout warnings appear, repeat the checklist from step one.

For testing fixes in isolation without navigating through your full application, refer to the widget preview documentation in [`skills/flutter-add-widget-preview/SKILL.md`](https://github.com/flutter/skills/blob/main/skills/flutter-add-widget-preview/SKILL.md).

## Practical Code Examples

Below are the canonical before-and-after implementations documented in the **Examples** section of the skill file.

### Fixing Unbounded Height: ListView Inside Column

**Problem:** "Vertical viewport was given unbounded height"

**Before:**

```dart
Column(
  children: <Widget>[
    const Text('Header'),
    ListView(
      children: const <Widget>[
        ListTile(title: Text('Item 1')),
        ListTile(title: Text('Item 2')),
      ],
    ),
  ],
)

```

**After:**

```dart
Column(
  children: <Widget>[
    const Text('Header'),
    Expanded(
      child: ListView(
        children: const <Widget>[
          ListTile(title: Text('Item 1')),
          ListTile(title: Text('Item 2')),
        ],
      ),
    ),
  ],
)

```

Wrapping the `ListView` in `Expanded` forces it to adopt the remaining space allocated by the parent `Column`, eliminating the unbounded height constraint.

### Fixing Unbounded Width: TextField Inside Row

**Problem:** "An InputDecorator…cannot have an unbounded width"

**Before:**

```dart
Row(
  children: [
    const Icon(Icons.search),
    TextField(),
  ],
)

```

**After:**

```dart
Row(
  children: [
    const Icon(Icons.search),
    Expanded(
      child: TextField(),
    ),
  ],
)

```

The `Expanded` widget establishes bounded width constraints by allocating a share of the `Row`'s available space to the `TextField`.

### Fixing RenderFlex Overflow: Long Text in Row

**Problem:** "A RenderFlex overflowed by X pixels on the right"

**Before:**

```dart
Row(
  children: [
    const Icon(Icons.info),
    const Text(
      'This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.',
    ),
  ],
)

```

**After:**

```dart
Row(
  children: [
    const Icon(Icons.info),
    Expanded(
      child: const Text(
        'This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.',
      ),
    ),
  ],
)

```

Using `Expanded` allows the `Text` widget to wrap and scroll within the allocated space rather than demanding infinite width.

## Summary

- Flutter layout debugging centers on the constraint contract where **constraints flow down** and **sizes flow up**.
- Common errors include unbounded height in `ListView`, unbounded width in `TextField`, and `RenderFlex` overflow in rows.
- The `flutter/skills` repository at [`skills/flutter-fix-layout-issues/SKILL.md`](https://github.com/flutter/skills/blob/main/skills/flutter-fix-layout-issues/SKILL.md) provides systematic diagnostic taxonomies and resolution workflows.
- Wrap offending widgets in `Expanded` or `Flexible` to provide bounded constraints and eliminate overflow.
- Always verify fixes using **hot reload** in debug mode before proceeding.

## Frequently Asked Questions

### What causes the "Vertical viewport was given unbounded height" error in Flutter?

This error occurs when a `ListView` or other scrollable widget is placed inside a `Column` without proper constraints. The `Column` passes unlimited height constraints downward, but scrollable widgets require bounded dimensions to calculate which children to render, causing the framework to throw an exception.

### How do I fix "An InputDecorator cannot have an unbounded width" errors?

Wrap the `TextField` or input widget in an `Expanded` or `Flexible` widget when placing it inside a `Row`. This forces the input field to respect the finite width allocated by the parent rather than attempting to expand infinitely.

### What is the difference between Expanded and Flexible for layout fixes?

`Expanded` forces a child to occupy all remaining space in the main axis, while `Flexible` allows the child to occupy space based on its flex factor but permits smaller sizes if needed. Both establish bounded constraints that resolve unbounded dimension errors.

### Where can I find official Flutter layout debugging documentation?

The `flutter/skills` repository contains authoritative documentation at [`skills/flutter-fix-layout-issues/SKILL.md`](https://github.com/flutter/skills/blob/main/skills/flutter-fix-layout-issues/SKILL.md). This resource includes constraint violation diagnostics, resolution workflows, and practical examples for common layout debugging scenarios.