Bug reporting in Flutter apps: shake, annotate, send

September 2, 2026 · 7 min read · by the Tracebird team

Web testers have devtools, a console, and a URL to paste. Your Flutter beta testers have a phone, one thumb, and possibly no network. Getting useful bug reports out of a mobile beta is a different problem, and most of it is solved by respecting four constraints.

The entry point is a gesture, not a button hunt

On a phone there is no corner of the screen you can permanently own without covering someone's UI. The convention testers already know is the shake: TestFlight popularised it, and a tester who hits a bug shakes the phone before they think about it. Support it, keep a floating button as the discoverable alternative, and leave a manual trigger for the settings screen. The report flow itself has to survive one-thumb use: capture, draw on the screenshot, one sentence, send.

Platform views will humiliate your screenshot code

The classic Flutter capture approach wraps the app in a RepaintBoundary and renders the tree to an image. It works until the screen contains a platform view: a WebView, a map, a video player. Those render outside Flutter's tree, so the capture comes back with a black or blank rectangle exactly where the interesting content was. A serious capture pipeline detects platform views on screen and falls back to a native capture (UIGraphicsImageRenderer on iOS, PixelCopy on Android) so the WebView's pixels are in the image. This is the detail to test first in any tool you evaluate, ours included: put a WebView on screen and shake. Our Flutter SDK docs describe how Tracebird handles the fallback.

Context without a console

No tester will paste logs from a phone. The SDK has to collect the context in the background, and on Flutter that means:

• debugPrint and framework errors via FlutterError.onError, kept in a ring buffer;
• navigation breadcrumbs from a NavigatorObserver, so the report says which screens led to the bug;
• network activity from your HTTP layer (a Dio interceptor or an http wrapper): method, URL, status, duration, never bodies;
• device model, OS version, app version and build number.

The point is the same as on web: the tester writes intent, the machine records facts. The captured context should be enumerable, capped, and documented, because it ships from inside your app.

Assume the network is missing

Betas happen on trains. A report that fails to send because the tester was offline is a report that never existed, so the queue is not optional: reports persist to disk, retry with backoff when connectivity returns, and carry an idempotency key so a retry can never file the same report twice. If a tester files three bugs in airplane mode, all three should arrive later, once, in order.

One inbox with your web app

The trap in mobile-only tooling is a second feedback silo: crash suites like Instabug are excellent at native observability, as we say in our comparison, but your dashboard, admin panel and marketing site live on the web and your testers touch those too. Whatever you pick, make sure a report from the phone and a report from the browser end up in the same list, deduplicated together. A beta is one product; its feedback should be one queue.