Repository navigation
[Widget Preview] Provide descriptive error when widget preview is unconstrained - #193005
Conversation
…constrained ## Description When a developer previews a widget that expects finite parent constraints (such as `SizedBox.expand` or expanding flex layouts), the preview scaffold previously crashed with cryptic `BoxConstraints forces an infinite width/height` assertions and secondary cascading failures (such as `hasSize` assertions and semantics traversal errors). This change improves the error handling when previews are rendered under unconstrained dimensions: - Intercepts unconstrained layout errors in the scaffold's `FlutterError.onError` handler and presents a structured `FlutterError` explaining that previews are unconstrained by default and directing developers to `@Preview(size: Size(width, height))` or explicit wrapper dimensions. - Traps layout exceptions at the preview card boundary (`_WidgetPreviewWrapperBox`), preventing secondary layout, paint, or semantics assertion cascades. - Renders `WidgetPreviewErrorWidget` locally for the affected preview card so the rest of the preview environment remains interactive. ## Related Issues Fixes flutter#192712 ## Tests - Added regression test in dev/integration_tests/widget_preview_scaffold/test/error_widget_test.dart.
github-actions
Bot
added
the
tool
…rrors - Scope layout error interception in _WidgetPreviewScaffoldState._handleFlutterError to _WidgetPreviewWrapperBox.isPerformingPreviewLayout and deduplicate cascading ancestor layout errors. - Guard _WidgetPreviewWrapperBox.hitTestChildren with child != null && child!.hasSize to avoid secondary assertion failures when pointer events hit an unlaid-out preview. - Assign _layoutError and _layoutStackTrace synchronously in WidgetPreviewWidgetState._handleLayoutError and reset them in reassemble() so hot reload recovers from layout errors. - Match unconstrained errors on exception messages (including 'was given an infinite size during layout') and preserve the original exception description without misclassifying non-unconstrained layout exceptions. - Add tests for hit-testing before post-frame error widget replacement, hot reload recovery of a TextField inside a Row, and non-unconstrained layout exceptions.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces layout error handling for widget previews, catching unconstrained dimension errors and displaying a WidgetPreviewErrorWidget. Feedback points out potential secondary layout crashes in the error widget when previewer constraints are unbounded, suggesting a fallback to a finite size. Additionally, the feedback notes that using static mutable fields to track layout state is not re-entrant, recommending a custom Zone with runZoned to store layout state robustly.
| if (_layoutError != null) { | ||
| return WidgetPreviewErrorWidget( | ||
| controller: widget.controller, | ||
| error: _layoutError!, | ||
| size: maxSizeConstraints.biggest, | ||
| stackTrace: _layoutStackTrace ?? StackTrace.current, | ||
| title: 'Failed to layout widget preview: ', | ||
| ); | ||
| } |
There was a problem hiding this comment.
If maxSizeConstraints is unbounded (which can happen if the previewer surface constraints are unbounded), calling maxSizeConstraints.biggest will result in infinite dimensions. Passing an infinite size to WidgetPreviewErrorWidget can cause a secondary layout crash when it tries to render, defeating the purpose of gracefully displaying the error.
We should constrain the size to a finite fallback using _kFallbackPreviewSize when constraints are unbounded, similar to how it is handled in _WidgetPreviewWrapperBox.performLayout. Also, since _layoutStackTrace is guaranteed to be non-null when _layoutError is non-null, we can safely use _layoutStackTrace! instead of the redundant ?? StackTrace.current.
| if (_layoutError != null) { | |
| return WidgetPreviewErrorWidget( | |
| controller: widget.controller, | |
| error: _layoutError!, | |
| size: maxSizeConstraints.biggest, | |
| stackTrace: _layoutStackTrace ?? StackTrace.current, | |
| title: 'Failed to layout widget preview: ', | |
| ); | |
| } | |
| if (_layoutError != null) { | |
| return WidgetPreviewErrorWidget( | |
| controller: widget.controller, | |
| error: _layoutError!, | |
| size: maxSizeConstraints.hasBoundedWidth && maxSizeConstraints.hasBoundedHeight | |
| ? maxSizeConstraints.biggest | |
| : _kFallbackPreviewSize, | |
| stackTrace: _layoutStackTrace!, | |
| title: 'Failed to layout widget preview: ', | |
| ); | |
| } |
| return WidgetPreviewErrorWidget( | ||
| controller: widget.controller, | ||
| error: error, | ||
| stackTrace: stackTrace, | ||
| size: maxSizeConstraints.biggest, | ||
| stackTrace: stackTrace, | ||
| ); | ||
| } |
There was a problem hiding this comment.
Similar to the layout error case, if maxSizeConstraints is unbounded, maxSizeConstraints.biggest will have infinite dimensions, which can cause a secondary layout crash in WidgetPreviewErrorWidget. We should safely fall back to _kFallbackPreviewSize if the constraints are unbounded.
return WidgetPreviewErrorWidget(
controller: widget.controller,
error: error,
size: maxSizeConstraints.hasBoundedWidth && maxSizeConstraints.hasBoundedHeight
? maxSizeConstraints.biggest
: _kFallbackPreviewSize,
stackTrace: stackTrace,
);| if (_layoutError != null) { | ||
| return WidgetPreviewErrorWidget( | ||
| controller: widget.controller, | ||
| error: _layoutError!, | ||
| size: maxSizeConstraints.biggest, | ||
| stackTrace: _layoutStackTrace ?? StackTrace.current, | ||
| title: 'Failed to layout widget preview: ', | ||
| ); | ||
| } |
There was a problem hiding this comment.
If maxSizeConstraints is unbounded (which can happen if the previewer surface constraints are unbounded), calling maxSizeConstraints.biggest will result in infinite dimensions. Passing an infinite size to WidgetPreviewErrorWidget can cause a secondary layout crash when it tries to render, defeating the purpose of gracefully displaying the error.
We should constrain the size to a finite fallback using _kFallbackPreviewSize when constraints are unbounded, similar to how it is handled in _WidgetPreviewWrapperBox.performLayout. Also, since _layoutStackTrace is guaranteed to be non-null when _layoutError is non-null, we can safely use _layoutStackTrace! instead of the redundant ?? StackTrace.current.
if (_layoutError != null) {
return WidgetPreviewErrorWidget(
controller: widget.controller,
error: _layoutError!,
size: maxSizeConstraints.hasBoundedWidth && maxSizeConstraints.hasBoundedHeight
? maxSizeConstraints.biggest
: _kFallbackPreviewSize,
stackTrace: _layoutStackTrace!,
title: 'Failed to layout widget preview: ',
);
}
| return WidgetPreviewErrorWidget( | ||
| controller: widget.controller, | ||
| error: error, | ||
| stackTrace: stackTrace, | ||
| size: maxSizeConstraints.biggest, | ||
| stackTrace: stackTrace, | ||
| ); | ||
| } |
There was a problem hiding this comment.
Similar to the layout error case, if maxSizeConstraints is unbounded, maxSizeConstraints.biggest will have infinite dimensions, which can cause a secondary layout crash in WidgetPreviewErrorWidget. We should safely fall back to _kFallbackPreviewSize if the constraints are unbounded.
return WidgetPreviewErrorWidget(
controller: widget.controller,
error: error,
size: maxSizeConstraints.hasBoundedWidth && maxSizeConstraints.hasBoundedHeight
? maxSizeConstraints.biggest
: _kFallbackPreviewSize,
stackTrace: stackTrace,
);
| static bool isPerformingPreviewLayout = false; | ||
|
|
||
| /// The first error reported to [FlutterError.onError] during the active | ||
| /// [performLayout] pass. | ||
| /// | ||
| /// Subsequent cascading layout errors (such as ancestor `RenderBox was not | ||
| /// laid out` assertions) within the same preview layout pass are suppressed, | ||
| /// and this error is forwarded to [onLayoutError] to populate the error card. | ||
| static Object? reportedPreviewLayoutError; |
There was a problem hiding this comment.
Using static mutable fields (isPerformingPreviewLayout and reportedPreviewLayoutError) to track layout state is not re-entrant. If a previewed widget contains nested previews, or if multiple layout passes occur concurrently/interleaved in tests, the inner layout's finally block will reset these static fields to false and null, leaving the outer layout's subsequent errors untracked.
To make this completely robust and re-entrant without global/static state, consider running child.layout inside a custom Zone using runZoned and storing the layout state/error holder in zoneValues. Since layout is synchronous, the error handler will run in the same zone and can safely access these values via Zone.current.
| static bool isPerformingPreviewLayout = false; | ||
|
|
||
| /// The first error reported to [FlutterError.onError] during the active | ||
| /// [performLayout] pass. | ||
| /// | ||
| /// Subsequent cascading layout errors (such as ancestor `RenderBox was not | ||
| /// laid out` assertions) within the same preview layout pass are suppressed, | ||
| /// and this error is forwarded to [onLayoutError] to populate the error card. | ||
| static Object? reportedPreviewLayoutError; |
There was a problem hiding this comment.
Using static mutable fields (isPerformingPreviewLayout and reportedPreviewLayoutError) to track layout state is not re-entrant. If a previewed widget contains nested previews, or if multiple layout passes occur concurrently/interleaved in tests, the inner layout's finally block will reset these static fields to false and null, leaving the outer layout's subsequent errors untracked.
To make this completely robust and re-entrant without global/static state, consider running child.layout inside a custom Zone using runZoned and storing the layout state/error holder in zoneValues. Since layout is synchronous, the error handler will run in the same zone and can safely access these values via Zone.current.
…iew card - Capture (Object, StackTrace) in _WidgetPreviewWrapperBox.reportedPreviewLayoutError and invoke onLayoutError after child.layout() when an error was reported via FlutterError.reportError without throwing (such as CustomPaint with Size.infinite inside a Row). - Guard _WidgetPreviewWrapperBox hitTestChildren, paint, and visitChildrenForSemantics with _hasValidChild so broken children are not painted on the failing frame. - Preserve the preview Card.outlined, name header, and ZoomablePreviewArea when rendering layout errors in WidgetPreviewWidgetState.build. - Make _WidgetPreviewWrapperBox layout error flags re-entrant, extract _errorSizeFor and _kUnconstrainedErrorPatterns, order required named parameters first in _WidgetPreviewWrapper, and remove unused message field from UnconstrainedWidgetPreviewException. - Add widget test for Row(children: [CustomPaint(size: Size.infinite)]) verifying the error card and preview name header are rendered without secondary overflow exceptions.
srawlins
left a comment
srawlins
left a comment
There was a problem hiding this comment.
Whoo, a big one! Great feature, and nice tests.
flutter-dashboard
Bot
removed
the
autosubmit
flutter/flutter@e89fd0a...d03768e 2026-10-02 [email protected] Roll Skia from 7b7326917e77 to 9e88bf828078 (8 revisions) (flutter/flutter#193694) 2026-10-02 [email protected] [Widget Preview] Provide descriptive error when widget preview is unconstrained (flutter/flutter#193005) 2026-10-02 [email protected] Roll Dart SDK from 0e7642b85457 to ac1a97aae47d (26 revisions) (flutter/flutter#193692) 2026-10-02 [email protected] Remove unused Fuchsia sysmem header files (flutter/flutter#193244) 2026-10-02 [email protected] [Windows] Preserve composing extent in setEditingState (flutter/flutter#189968) 2026-10-02 [email protected] [docs] Make Border.symmetric docs more explicit about their arguments (flutter/flutter#193222) 2026-10-02 [email protected] [Embedder] Support render texture for vulkan (flutter/flutter#188855) 2026-10-02 [email protected] Updated Remaining Engine Defaults to SDK 37 (flutter/flutter#190429) 2026-10-02 [email protected] Document that enableSuggestions: false can disable keyboard languages on Android (flutter/flutter#192714) 2026-10-02 [email protected] [flutter_tools] Explicitly track host CPU architecture in command result analytics (flutter/flutter#191836) 2026-10-02 [email protected] [web] Preserve DOM focus on role update and honor isAccessibilityFocusBlocked (flutter/flutter#192963) 2026-10-02 [email protected] [flutter_tools] Include base href in web hot reload script paths (flutter/flutter#193678) 2026-10-02 [email protected] [Impeller] Deduplicate GLES render pass state (flutter/flutter#193427) 2026-10-02 [email protected] Roll Skia from f2d68e0b8863 to 7b7326917e77 (16 revisions) (flutter/flutter#193676) 2026-10-01 [email protected] Fix analysis failures due to missing `const` (flutter/flutter#193685) 2026-10-01 [email protected] Removes a11y_assessment app (flutter/flutter#193671) 2026-10-01 [email protected] test: configure Xvfb and openbox for windowing_test (flutter/flutter#193529) 2026-10-01 [email protected] Sync CHANGELOG.md from stable (flutter/flutter#193666) 2026-10-01 [email protected] Avoid using relative path in Process.start (flutter/flutter#193664) 2026-10-01 [email protected] [AGP 9.1.0 Migration #6] Deliver Flutter assets as a generated assets source directory on the app path (flutter/flutter#192488) 2026-10-01 [email protected] ci(bringup): android_java17_build_android_host_app_with_module_aar is green (flutter/flutter#193580) 2026-10-01 [email protected] [flutter_tools] Fix Use dependency graph to determine plugin initialization order (flutter/flutter#191591) 2026-10-01 [email protected] [flutter_tools] Migrate DaemonCommand and Daemon domains to constructor DI (flutter/flutter#193542) If this roll has caused a breakage, revert this CL and set the roller to dry run mode using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC [email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
2 participants
Description
When a developer previews a widget that expects finite parent constraints (such as
SizedBox.expandor expanding flex layouts), the preview scaffold previously crashed with crypticBoxConstraints forces an infinite width/heightassertions and secondary cascading failures (such ashasSizeassertions and semantics traversal errors).This PR improves the error handling when previews are rendered under unconstrained dimensions:
FlutterError.onErrorhandler and presents a structuredFlutterErrorexplaining that previews are unconstrained by default and directing developers to@Preview(size: Size(width, height))or explicit wrapper dimensions._WidgetPreviewWrapperBox), preventing secondary layout, paint, or semantics assertion cascades.WidgetPreviewErrorWidgetlocally for the affected preview card so the rest of the preview environment remains interactive.Related Issue
Fixes #192712
Tests
dev/integration_tests/widget_preview_scaffold/test/error_widget_test.dart.