Flutter error handling: FlutterError.onError vs PlatformDispatcher.onError

Flutter sends errors down separate channels, and you need a handler on each. FlutterError.onError receives errors the framework catches during build, layout, paint and other framework callbacks. PlatformDispatcher.instance.onError receives uncaught errors outside those callbacks, such as a failed await in a button handler or a platform channel call. Errors in other isolates reach neither, so you either use Isolate.run (which passes errors back to the caller) or attach an error listener. Set the first two in main() before runApp(), keep FlutterError.presentError so you still see errors in the console, and replace ErrorWidget.builder so release users don't see a bare grey box.

Below: what each channel catches, how zones and runZonedGuarded fit in today, release versus debug behaviour, obfuscation symbols, and a complete main(). If you want reporting without wiring it yourself, the Codeskop Flutter docs show the one-call setup. Related reading: Android ANRs (Flutter apps on Android get ANRs too), OkHttp interceptors for network monitoring, and how Codeskop compares with Firebase Crashlytics.

The three error channels in Flutter#

Native crashes (a crash in Kotlin, Java, Swift or C code under your app) are a fourth category. Dart handlers never see them; you need a native crash reporter for those.

Framework errors: FlutterError.onError

By default, FlutterError.onError calls FlutterError.presentError, which dumps the error to the device log. Override it to report, and keep presentError so local debugging still works:

1FlutterError.onError = (FlutterErrorDetails details) {2  FlutterError.presentError(details);          // keep console output3  myReporter.report(details.exception, details.stack, fatal: false);4};

A framework error usually doesn't kill the app. The broken widget is replaced by an ErrorWidget and the rest of the UI keeps running, which is why many tools record these as handled (non-fatal) errors.

Async and platform errors: PlatformDispatcher.onError

An exception thrown after an await in an onPressed handler isn't inside a framework callback any more, so FlutterError.onError never sees it. Flutter forwards these to the PlatformDispatcher:

1PlatformDispatcher.instance.onError = (Object error, StackTrace stack) {2  myReporter.report(error, stack, fatal: true);3  return true;   // handled: don't let it propagate further4};

Returning true tells the engine you handled the error. Returning false lets it fall through to the default behaviour (logging).

Errors in isolates

Each isolate has its own error handling, so handlers you set in the main isolate don't see errors in a background isolate. For one-off work, prefer Isolate.run: if the computation throws, the returned future completes with that error and your normal try/catch (or the platform dispatcher) handles it:

1Future<List<Order>> parseOrders(String json) async {2  try {3    return await Isolate.run(() => decodeOrders(json));4  } catch (e, stack) {5    myReporter.report(e, stack, fatal: false);6    rethrow;7  }8}

For a long-lived isolate started with Isolate.spawn, pass an onError port. Errors arrive as a two-element list: the error and the stack trace, both as strings:

1final errors = ReceivePort();2errors.listen((dynamic message) {3  final pair = message as List<dynamic>;4  myReporter.report(5    pair[0] as String,6    StackTrace.fromString(pair[1] as String),7    fatal: false,8  );9});10 11await Isolate.spawn(syncWorker, initialMessage, onError: errors.sendPort);

Zones and runZonedGuarded: where they fit now#

Before PlatformDispatcher.onError existed (it arrived in Flutter 3.3), the standard advice was to wrap runApp in runZonedGuarded so the zone's error callback caught uncaught async errors. Many crash SDKs still use a guarded zone as a safety net.

Zones come with a trap. Since Flutter 3.10, debug builds print a "Zone mismatch" warning if the bindings were initialised in one zone and runApp is called in another. The usual cause is calling WidgetsFlutterBinding.ensureInitialized() before entering runZonedGuarded. The fix is to call ensureInitialized() inside the same zone as runApp. Flutter's own guidance is to avoid zones where you can, since they are hard to debug.

In practice:

• Writing your own setup: use FlutterError.onError plus PlatformDispatcher.instance.onError, with no zone.
• Using a crash SDK that wraps main() in a zone: let it own the zone, and make sure ensureInitialized() and runApp() both run inside it.

ErrorWidget.builder: release vs debug behaviour#

When a widget throws during build, Flutter shows ErrorWidget in its place. By default, debug builds show the error message in red and release builds show a plain grey background. Neither is great for users, so replace it with something friendlier. Flutter's docs set it inside MaterialApp.builder:

1MaterialApp(2  builder: (context, widget) {3    Widget error = const Text('Something went wrong on this screen.');4    if (widget is Scaffold || widget is Navigator) {5      error = Scaffold(body: Center(child: error));6    }7    ErrorWidget.builder = (errorDetails) => error;8    if (widget != null) return widget;9    throw StateError('widget is null');10  },11);

Replacing the widget doesn't report anything. The error still goes to FlutterError.onError, so reporting stays there.

On a budget Android phone, a build error inside a list item can leave a screen half-rendered rather than crashing outright. Users on patchy connections often assume it's the network and retry. Reporting framework errors as handled errors is how you find these screens.

Obfuscation and symbols#

For release builds, you can obfuscate Dart code and split debug info out of the binary:

1flutter build appbundle --obfuscate --split-debug-info=build/symbols/android

The Flutter docs cover the details:

• Obfuscation only applies to release builds. It's supported for Android (aar, apk, appbundle), iOS (ios, ios-framework, ipa), macOS, Linux and Windows, but not web, which uses minification instead.
• Back up the symbols directory for every release. Without it you can't read obfuscated stack traces.
• To translate a trace, use the symbols file that matches the device architecture:

1flutter symbolize -i crash_trace.txt -d build/symbols/android/app.android-arm64.symbols

• Code that depends on runtimeType.toString() matching a class name breaks once obfuscated. Enum names are not obfuscated.

A good habit is to make symbols part of your release pipeline: name the folder after the version (symbols/1.8.2+57/) and archive it with the build artefacts.

A complete main() setup (no SDK)#

This is a self-contained setup using only Flutter APIs. Swap ErrorReporter for whatever you send errors to.

1import 'dart:ui';2 3import 'package:flutter/material.dart';4 5final reporter = ErrorReporter();6 7Future<void> main() async {8  WidgetsFlutterBinding.ensureInitialized();9  await reporter.initialize();10 11  // 1. Framework errors (build, layout, paint): usually non-fatal12  FlutterError.onError = (details) {13    FlutterError.presentError(details);14    reporter.report(details.exception, details.stack, fatal: false);15  };16 17  // 2. Uncaught async and platform errors18  PlatformDispatcher.instance.onError = (error, stack) {19    reporter.report(error, stack, fatal: true);20    return true;21  };22 23  runApp(const MyApp());24}

Then add a friendlier ErrorWidget.builder as shown above, use Isolate.run or onError: for background isolates, and in debug builds keep presentError so nothing is hidden.

Using Codeskop.runGuarded#

The codeskop_tracker plugin wires all of this up in one call. It requires Flutter 3.19+ and Dart 3.3+, and Android minSdk 24.

1dependencies:2  codeskop_tracker: ^0.3.0

1import 'package:codeskop_tracker/codeskop_tracker.dart';2import 'package:flutter/material.dart';3 4void main() {5  Codeskop.runGuarded(() async {6    await Codeskop.init(apiKey: 'cs_live_pk_YOUR_KEY', endpoint: 'https://api.codeskop.com');7    runApp(const MyApp());8  });9}

According to the docs, runGuarded calls WidgetsFlutterBinding.ensureInitialized() and sets up FlutterError.onError, PlatformDispatcher.onError and a guarded zone for uncaught async errors. Because the binding is initialised inside the same zone as runApp, you avoid the zone mismatch above. Flutter's red error screen and console output still work.

What's reported:

• Uncaught Dart errors as crashes, with the Dart stack trace.
• Framework errors as handled exceptions.
• Native crashes and ANRs in the Android layer, from the native Codeskop SDK the plugin brings in. ANR detection is on the Starter plan and above (see pricing); crashes and handled errors are on every plan, including Free (10,000 events/month as of October 2026).

Events are written to the device first and uploaded when there's a connection, so errors from users who drop off the network (common on rural 3G or when a capped data bundle runs out) aren't lost.

To report errors you catch yourself:

1try {2  await checkout();3} catch (e, stack) {4  Codeskop.recordError(e, stack);   // reported as a handled exception5  showErrorBanner();6}

If you already manage your own zone, call registerErrorHooks() instead of runGuarded and forward zone errors:

1void main() {2  runZonedGuarded(() async {3    WidgetsFlutterBinding.ensureInitialized();4    Codeskop.registerErrorHooks();5    await Codeskop.init(apiKey: 'cs_live_pk_YOUR_KEY', endpoint: 'https://api.codeskop.com');6    runApp(const MyApp());7  }, (error, stack) => Codeskop.recordError(error, stack, fatal: true));8}

The plugin doesn't include an HTTP interceptor. To see failed API calls (Starter and above), call Codeskop.captureApiError from your own Dio or http interceptor; the Flutter docs have a ready-made Dio example. Isolates you spawn still need the Isolate.run / onError handling above, reporting with Codeskop.recordError.