No error leaves
uncaught, none leaves unlogged.

Two halves: a net and a vocabulary.

Good error handling is two things working together. An outer safety net, a small set of global handlers so nothing crashes silently or escapes unlogged. And an inner vocabulary, typed domain errors your code passes around deliberately, so a failure is a value you designed for, not a surprise that blows up three layers away.

The shape of the whole system

Read top to bottom, this is the path of a single failure. Every chapter that follows builds one of these rows.

• Throw: something fails, a socket drops, a parse breaks, a widget overflows.
• Catch: either you catch it on purpose at a boundary, or a global handler catches what you didn't.
• Map: the low-level exception becomes a typed Failure your app understands.
• Surface: the UI shows a real message and a way forward (retry, go back), never a raw stack trace.
• Log: the same failure is reported to PostHog with screen, user, and breadcrumbs attached.

Know where each error is caught.

Flutter throws errors in several different places, and each place has a different catch point. Wire the wrong one and the error slips past. Pick an error kind below to see where it surfaces and how you handle it.

Catch what you didn't expect.

Three hooks cover everything that escapes your own try/catch blocks. Wire all three at startup so an unexpected error becomes a logged event and a graceful screen, never a silent crash. This is the outermost layer, and you set it once.

// core/errors/error_bootstrap.dart
import 'dart:isolate';
import 'dart:ui';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';

void installErrorHandlers(ErrorReporter reporter) {
  // 1. Flutter framework errors: build, layout, paint.
  FlutterError.onError = (FlutterErrorDetails details) {
    FlutterError.presentError(details);   // keep the console output
    reporter.report(
      details.exception,
      details.stack ?? StackTrace.current,
      context: {'library': details.library ?? 'flutter'},
    );
  };

  // 2. Everything async that escapes a zone: the catch-all.
  PlatformDispatcher.instance.onError = (error, stack) {
    reporter.report(error, stack, fatal: true);
    return true;   // true = handled, don't re-throw
  };

  // 3. Errors thrown on the root isolate.
  Isolate.current.addErrorListener(RawReceivePort((List<dynamic> pair) {
    reporter.report(pair.first, pair.last as StackTrace? ?? StackTrace.current, fatal: true);
  }).sendPort);

  // Bonus: a friendly widget instead of the grey error box.
  ErrorWidget.builder = (details) => AppErrorBox(
    message: kReleaseMode ? 'This screen hit a problem.' : details.exceptionAsString(),
  );
}

Call it from main before the app runs, after you've built the reporter:

// main.dart
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final reporter = await buildReporter();   // sets up PostHog, see Ch.08
  installErrorHandlers(reporter);

  runApp(const ProviderScope(child: MyApp()));
}

What about runZonedGuarded?

You'll see older guides wrap runApp in runZonedGuarded. Since Flutter 3.3, PlatformDispatcher.instance.onError covers the same uncaught-async case with less ceremony, so the three hooks above are the current default. Reach for a zone only when you need to capture print output or run setup code that itself might throw before the handlers are installed.

Make failure a value.

Instead of letting raw DioExceptions and PostgrestExceptions travel up into your widgets, define a small sealed hierarchy of Failures your whole app speaks. A sealed class means the compiler forces you to handle every case when you switch on it, so a new failure type can't be silently ignored.

// core/errors/failure.dart
sealed class Failure {
  const Failure(this.message);
  final String message;   // already user-safe, no stack traces
}

class NetworkFailure extends Failure {
  const NetworkFailure(super.message, {this.statusCode});
  final int? statusCode;
}

class CacheFailure extends Failure {
  const CacheFailure(super.message);
}

class ValidationFailure extends Failure {
  const ValidationFailure(super.message, {this.field});
  final String? field;
}

class AuthFailure extends Failure {
  const AuthFailure(super.message);
}

class UnexpectedFailure extends Failure {
  const UnexpectedFailure([super.message = 'Something went wrong.']);
}

One mapper, not one per repository

The translation from raw exception to Failure is the same logic everywhere, so it belongs in a single place in core/, not as a private method copied into every repository. A top-level function that switches on the runtime type handles Dio, Supabase, and the common Dart exceptions in one spot. Add a new infrastructure exception once, here, and every repository benefits.

// core/errors/failure_mapper.dart  ::  the ONLY file that imports Dio + Supabase
import 'dart:async';
import 'dart:io';
import 'package:dio/dio.dart';
import 'package:supabase_flutter/supabase_flutter.dart';

Failure failureFrom(Object error) => switch (error) {
  Failure f          => f,                       // already mapped, pass through
  DioException e     => _fromDio(e),
  AuthException e    => AuthFailure(e.message),       // Supabase auth
  PostgrestException e => NetworkFailure(e.message),     // Supabase data
  SocketException _  => const NetworkFailure('No internet connection.'),
  TimeoutException _ => const NetworkFailure('The request timed out.'),
  FormatException _  => const ValidationFailure('Received malformed data.'),
  _                  => const UnexpectedFailure(),
};

Failure _fromDio(DioException e) => switch (e.type) {
  DioExceptionType.connectionTimeout ||
  DioExceptionType.receiveTimeout =>
    const NetworkFailure('The request timed out. Check your connection.'),
  DioExceptionType.badResponse =>
    NetworkFailure('The server returned an error.', statusCode: e.response?.statusCode),
  DioExceptionType.connectionError =>
    const NetworkFailure('Could not reach the server.'),
  _ => const NetworkFailure('Network request failed.'),
};

Prefer calling it on the type? Expose the same logic as a factory on the sealed class, factory Failure.from(Object e) => failureFrom(e), and write Failure.from(e) at call sites. Either way, the Failure passes straight through if it's already mapped, so calling it twice is harmless.

Two ways to return a failure

You can keep throwing (now with typed errors) or return an explicit Result. Both are valid; the difference is whether failure is visible in the function's type. Flip between them:

// core/errors/result.dart  ::  failure is in the return type
sealed class Result<T> {
  const Result();
}

class Ok<T> extends Result<T> {
  const Ok(this.value);
  final T value;
}

class Err<T> extends Result<T> {
  const Err(this.failure);
  final Failure failure;
}

// The caller cannot forget the failure case:
final result = await repo.sync();
switch (result) {
  Ok(:final value) => show(value),
  Err(:final failure) => show(failure.message),
}

// Throwing typed failures  ::  shorter, but failure is invisible in the signature
Future<SyncReport> sync() async {
  final res = await client.post('/sync');
  if (res.statusCode != 200) {
    throw NetworkFailure('Sync rejected.', statusCode: res.statusCode);
  }
  return SyncReport.fromJson(res.data);
}

// The caller must remember to catch:
try {
  final report = await repo.sync();
  show(report);
} on Failure catch (f) {
  show(f.message);
}

Translate at the edge.

This is the single most important discipline in the whole guide. The repository is the one place that knows about Dio, sockets, and SQL. So it's the one place that catches their exceptions and maps them to your Failure vocabulary. Past this line, nothing upstream ever sees a DioException again.

// features/sync/repo/sync_repository.dart
class SyncRepository {
  SyncRepository(this._ref);
  final Ref _ref;   // reads apiClient + reporter internally

  Future<Result<SyncReport>> sync() async {
    try {
      final client = _ref.read(apiClientProvider);
      final res = await client.post('/sync');
      return Ok(SyncReport.fromJson(res.data));
    } catch (e, st) {
      // report the raw error + stack here, while they're still in scope
      _ref.read(errorReporterProvider).report(e, st, context: {'endpoint': '/sync'});
      // then hand the UI a typed, user-safe Failure via the shared mapper
      return Err(failureFrom(e));
    }
  }
}

One catch, one report, one failureFrom. Every repository in the app follows this exact three-line shape, and none of them owns mapping logic. When you add a new backend exception type, you edit failure_mapper.dart once and all repositories pick it up.

What this buys you

• Controllers and widgets only ever match on Failure subtypes, never on Dio internals. Swap Dio for http tomorrow and nothing upstream changes.
• The report-to-PostHog call lives here too, where the raw exception and stack are still in scope, before they're flattened into a friendly message.
• The user-facing message is written once, in the mapper, in plain language. No screen has to invent its own wording.

Show a way forward.

An error on screen is a moment for direction, not an apology. With Riverpod, the controller turns a Failure into AsyncError, and the view renders one of three states. Errors get a message and a retry; they never show a raw exception.

// features/sync/controllers/sync_controller.dart  (plain Dart, no code-gen)
class SyncController extends AsyncNotifier<SyncReport?> {
  @override
  Future<SyncReport?> build() async => null;   // idle until run()

  Future<void> run() async {
    state = const AsyncLoading();
    final result = await ref.read(syncRepositoryProvider).sync();
    state = switch (result) {
      Ok(:final value)   => AsyncData(value),
      Err(:final failure) => AsyncError(failure, StackTrace.current),
    };
  }
}

final syncControllerProvider =
    AsyncNotifierProvider<SyncController, SyncReport?>(SyncController.new);

The view watches the state, listens for failures to fire a snackbar, and renders an error view with a retry button:

// features/sync/views/sync_screen.dart
final state = ref.watch(syncControllerProvider);

// Side effect on failure: a snackbar. No rebuild, fires once per change.
ref.listen(syncControllerProvider, (prev, next) {
  if (next case AsyncError(:final error)) {
    final msg = error is Failure ? error.message : 'Something went wrong.';
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(msg)));
  }
});

return state.when(
  loading: () => const Center(child: CircularProgressIndicator()),
  data:    (report) => report == null ? const SyncIdle() : SyncSummary(report: report),
  error:   (e, _) => ErrorView(
    message: e is Failure ? e.message : 'Something went wrong.',
    onRetry: () => ref.read(syncControllerProvider.notifier).run(),
  ),
);

The shortcut: AsyncValue.guard

When a controller just wraps a throwing call, AsyncValue.guard handles the loading/data/error transitions for you, so you don't write the try/catch by hand:

Future<void> run() async {
  state = const AsyncLoading();
  // guard() runs the body, returns AsyncData on success or AsyncError on throw
  state = await AsyncValue.guard(() => ref.read(syncRepositoryProvider).syncOrThrow());
}

Every failure, one exit.

All paths converge here. Define a single ErrorReporter interface so your repositories and global hooks depend on an abstraction, not on PostHog directly. The PostHog implementation is the only file that imports the SDK, which keeps reporting swappable and testable.

// core/errors/error_reporter.dart  ::  the abstraction everything depends on
abstract interface class ErrorReporter {
  Future<void> report(
    Object error,
    StackTrace stack, {
    Map<String, Object>? context,
    bool fatal,
  });
  void breadcrumb(String message);
  Future<void> identifyUser(String id);
}

// core/errors/posthog_error_reporter.dart  ::  the ONLY file that imports PostHog
class PostHogErrorReporter implements ErrorReporter {
  @override
  Future<void> report(
    Object error,
    StackTrace stack, {
    Map<String, Object>? context,
    bool fatal = false,
  }) async {
    // NEVER do Posthog().capture('$exception', ...). Use captureException.
    await Posthog().captureException(
      error: error,
      stackTrace: stack,
      properties: {if (context != null) ...context, 'fatal': fatal},
    );
  }

  @override
  void breadcrumb(String message) => Posthog().addExceptionStep(message);

  @override
  Future<void> identifyUser(String id) => Posthog().identify(userId: id);
}

// expose it as a provider so repositories can read it
final errorReporterProvider =
    Provider<ErrorReporter>((ref) => PostHogErrorReporter());

Log the wins, not just the wrecks

Exceptions are only half of what PostHog is for. It's an analytics tool first, so the successful path deserves events too. A sync_completed next to a sync_started is what lets you measure a real success rate and build a funnel, and spot the exact step where users fall out. Errors use captureException; product events use capture. Give them a sibling abstraction so the split stays clean:

// core/telemetry/analytics.dart  ::  success + lifecycle events
abstract interface class Analytics {
  Future<void> track(String event, {Map<String, Object>? properties});
}

// core/telemetry/posthog_analytics.dart
class PostHogAnalytics implements Analytics {
  @override
  Future<void> track(String event, {Map<String, Object>? properties}) =>
      Posthog().capture(eventName: event, properties: properties ?? const {});
}

final analyticsProvider =
    Provider<Analytics>((ref) => PostHogAnalytics());

Now the controller emits a product event on the way in and on success, while the failure still flows through AsyncError exactly as before (the exception was already reported inside the repo, so there's no double-logging here):

// features/sync/controllers/sync_controller.dart
Future<void> run() async {
  final analytics = ref.read(analyticsProvider);
  state = const AsyncLoading();
  analytics.track('sync_started');

  final result = await ref.read(syncRepositoryProvider).sync();
  switch (result) {
    case Ok(:final value):
      analytics.track('sync_completed', properties: {
        'records': value.count,
        'duration_ms': value.elapsedMs,
      });
      state = AsyncData(value);
    case Err(:final failure):
      state = AsyncError(failure, StackTrace.current);
  }
}

Screen views for free, through GoRouter

You don't hand-track navigation. PostHog ships PosthogObserver, a NavigatorObserver that emits a $screen event on every route change. GoRouter accepts it through its observers list, so wiring it is one line, plus one rule you cannot skip.

// core/router/app_router.dart
import 'package:go_router/go_router.dart';
import 'package:posthog_flutter/posthog_flutter.dart';

final appRouter = GoRouter(
  // records a $screen event automatically on every navigation
  observers: [
    PosthogObserver(
      // optional: count full pages only, skip dialogs and overlays
      routeFilter: (route) => route is PageRoute,
    ),
  ],
  routes: [
    GoRoute(
      name: 'SyncScreen',   // REQUIRED: an unnamed route is NOT recorded
      path: '/sync',
      builder: (context, state) => const SyncScreen(),
    ),
    GoRoute(
      name: 'ProfileScreen',
      path: '/profile/:id',
      builder: (context, state) => ProfileScreen(id: state.pathParameters['id']!),
    ),
  ],
);

This pays off twice. For analytics, you get screen-to-screen funnels without touching a single widget. For debugging, every $screen lands in the user's timeline just before any $exception they hit, so the crash arrives with a free trail of where they'd just been. You rarely need to breadcrumb navigation by hand once this is on.

Watch a failure travel

Pick where the error starts, then throw it. No matter the origin, it converges on the one report() call and leaves as a single PostHog $exception event. The panel on the right is the event PostHog receives.

Setup, autocapture, and context.

PostHog can wire itself into the same three Flutter hooks from Chapter 3 automatically, or you can route them by hand through your reporter. Here's the setup, the autocapture flags, and how to attach the context that turns a stack trace into a debuggable issue.

Install

# pubspec.yaml
dependencies:
  posthog_flutter: ^5.0.0

Initialize once, in main

// main.dart
import 'package:flutter/foundation.dart';
import 'package:posthog_flutter/posthog_flutter.dart';

Future<ErrorReporter> buildReporter() async {
  final config = PostHogConfig('phc_yourProjectApiKey')
    ..host = 'https://eu.i.posthog.com'   // or us.i.posthog.com
    ..debug = kDebugMode
    ..captureApplicationLifecycleEvents = true;

  // Let PostHog auto-capture the three global hooks for you.
  config.errorTrackingConfig.captureFlutterErrors = true;
  config.errorTrackingConfig.capturePlatformDispatcherErrors = true;
  config.errorTrackingConfig.captureIsolateErrors = true;
  config.errorTrackingConfig.captureNativeExceptions = true;   // SDK 5.22.0+

  // Mark your own package so its frames are highlighted in the UI.
  config.errorTrackingConfig.inAppIncludes.add('package:myapp');

  await Posthog().setup(config);
  return PostHogErrorReporter();
}

The autocapture flags

Each flag maps onto exactly one hook from Chapter 3. That's the whole connection: PostHog's autocapture is those same hooks, wired for you.

Attach context that makes errors debuggable

A bare stack trace is hard to act on. Identify the user, leave breadcrumbs as they move, and pass properties at capture time. PostHog groups events into issues and ties each to the user's session.

// when the user signs in: tie every later exception to them
await reporter.identifyUser(user.id);   // stable id, not an email

// as they navigate: lightweight breadcrumbs on the timeline
reporter.breadcrumb('opened SyncScreen');
reporter.breadcrumb('tapped Sync now');

// at capture time: properties you can filter and group issues by
reporter.report(error, stack, context: {
  'screen': 'SyncScreen',
  'endpoint': '/sync',
  'severity': 'error',
});

Redact before it leaves the device

Use beforeSend to strip anything sensitive from events on the client, before they're sent. One place to enforce that PII never reaches your analytics:

// in your PostHogConfig setup (SDK 5.13.0+)
config.beforeSend = (event) {
  event?.properties.remove('email');
  event?.properties.remove('auth_token');
  return event;   // return null to drop the event entirely
};

Ways it goes quietly wrong.

Error handling fails silently by nature, so these are the ones that bite weeks later. Skim them now.