Users of a Flutter release build see a grey box where a crashed widget should be, yet the crash reporter shows nothing; what is missing, and how do you fix it?

## Reading the symptom A **grey box** where a widget should be is the release (and profile) look of the default **`ErrorWidget`**. It proves three things: 1. A widget-building callback threw: a `build` method, a `LayoutBuilder` builder, or a list item builder. 2. The framework **caught** the exception. Nothing crashed, and the rest of the screen still works. 3. Before swapping in the replacement, the element called `FlutterError.reportError(details)`, so **`FlutterError.onError` ran with the full details**. "The reporter shows nothing" therefore means the problem is on the `FlutterError.onError` side, not somewhere deep in the app. ## Why the reporter never saw it | Cause | How it happens | How to spot it | |---|---|---| | hook never set | only `PlatformDispatcher.instance.onError` or a zone guard was wired; both see **uncaught** errors, and this one was caught | `FlutterError.onError` is still the default presenter | | hook overwritten | a later `FlutterError.onError = ...` in a feature module or debug tool replaced the reporter's handler; it is one static field, and the last assignment wins | search the codebase for assignments | | hook filters it out | the handler drops errors by `library`, by `silent`, or by a sampling rule | read the handler | | reporter not ready | errors thrown before the reporter finished initialising are lost | the order of work in `main()` | The device log (`flutter logs`, or the platform log viewer) usually still has the default dump, because `presentError` prints outside debug too, just without the diagnostics tree. ## Fixing the wiring 1. In `main()`, before `runApp`, initialise the reporter and then set `FlutterError.onError`. 2. In the handler, call `FlutterError.presentError(details)` first to keep console and IDE output. 3. Forward `details.exception` and `details.stack`, plus `details.library` and `details.context?.toString()`. In release, `informationCollector` adds less, because the framework attaches the failing element's debug creator only in debug mode, so the context text matters. 4. If another handler might already be installed, **chain it** instead of replacing it: keep `final previous = FlutterError.onError;` and call `previous?.call(details)`. 5. Keep `PlatformDispatcher.instance.onError` for the uncaught class, returning `true` once the error is recorded. 6. Add a check to code review: exactly one place assigns these global hooks. ## Finding the real bug - The report's **context** reads like "building ProductCard(...)", which names the widget whose build threw. - The **exception type** usually points at data: a `!` on a null the test data never had, a `RangeError` on an empty list, a failed `as` cast on a JSON field. - Check what changed in the **data**, not only in the code. A release that passed every test can still meet a server response, a locale or a stored value the tests never used, and the grey box appears only for the users who have it. - Group reports by the context text. One widget failing for many users is a data or contract problem; many widgets failing at once usually points to something shared, such as a theme or a localisation lookup. - Reproduce with the same data in **profile mode** if you need release-like behaviour with a readable stack, or in debug to get the red screen and the full diagnostics tree. - If release stack traces are obfuscated, symbolicate them with the symbols saved at build time. That process belongs to the release build set-up. ## Improving what users see The default grey box is honest but ugly. Assign **`ErrorWidget.builder`** in release to a cheap fallback that fits the design, such as a neutral panel saying the section could not load. The API doc stresses doing as little work as possible there: it runs right after an exception thrown mid-build, when the surrounding tree and the `BuildOwner` may be fragile. So use no providers, no network calls and no animation. Keep the default in debug so developers still see the message. ## What to monitor afterwards - The count of framework-caught errors per release, separate from uncaught ones. The two hooks make this easy, since each can tag its source. - Grey boxes are **non-fatal** from the process's point of view, but they are real user-visible failures, so do not filter them out as noise. - `silent` errors, such as image loading failures, are a separate choice. Forward them at a lower severity or drop them, but decide on purpose.