Error Handling in Async Dart

This is Part 7 of the Async & Concurrency in Dart series. We can now create and consume futures and streams. But every one of those operations can fail — the network drops, JSON is malformed, a file is missing. Getting error handling right in async code is harder than it looks, because errors travel through time and across event-loop turns. A try/catch that looks correct can silently miss the very error you wrote it for.

This post nails down the rules: when try/catch works, when it doesn't, how Future and Stream errors differ, and how to make sure a failure never vanishes unhandled.

The one rule that explains most bugs

From Part 3, repeated because it's that important:

try/catch only catches an async error if you await the failing future inside the try. No await, no catch.

// ✅ WORKS — the future is awaited inside the try.
Future<void> good() async {
  try {
    await riskyFetch();        // error propagates to catch
  } catch (e) {
    print('caught: $e');
  }
}

// ❌ BROKEN — not awaited; error escapes the try entirely.
Future<void> bad() async {
  try {
    riskyFetch();              // fire-and-forget; try block exits immediately
  } catch (e) {
    print('never runs');       // the error becomes UNHANDLED, later
  }
}

Why? try/catch is synchronous — it only guards code that runs while control is inside the block. Without await, riskyFetch() just starts the work and returns a future; control leaves the try immediately, and the failure surfaces later (a different event-loop turn) with no try around it. The await is what keeps control "inside" the block until the future settles.

try/catch/finally with await

With await, async error handling reads exactly like synchronous error handling — that's the whole appeal:

Future<User> loadUser(String id) async {
  showSpinner();
  try {
    final response = await http.get('/users/$id');  // may throw
    final user = User.fromJson(response);            // may throw (bad JSON)
    return user;
  } on SocketException catch (e) {
    throw AppError('Network down: $e');               // translate the error
  } on FormatException catch (e) {
    throw AppError('Bad response: $e');
  } catch (e, stack) {
    log('unexpected', e, stack);                      // catch-all + stack trace
    rethrow;                                           // don't swallow what you can't handle
  } finally {
    hideSpinner();                                     // always runs
  }
}

Three things worth calling out:

• on Type catch (e) lets you handle specific error types differently (network vs parse vs everything-else).
• catch (e, stack) gives you the StackTrace as a second parameter — log it; you'll want it.
• finally runs whether the try succeeded, threw, or you rethrew — the place for cleanup (hide spinners, close files).

rethrow, not throw e

When you catch an error only to log it and pass it on, use rethrow — it preserves the original stack trace. throw e resets the stack to the current line, destroying the trail back to the real cause:

} catch (e) {
  log(e);
  rethrow;   // ✅ keeps original stack trace
  // throw e; // ❌ loses where it actually came from
}

Errors with the Future callback API

If you're using .then() instead of await, errors travel down the chain to .catchError() (the catch) and cleanup goes in .whenComplete() (the finally) — as covered in Part 2:

riskyFetch()
    .then((data) => process(data))
    .catchError((e) => print('caught: $e'))   // handles errors from EITHER step
    .whenComplete(() => hideSpinner());

A subtlety: .catchError catches errors from everything before it in the chain (the original future and the .then callback). You can also scope it with test: to only catch certain errors:

.catchError(
  (e) => fallbackValue,
  test: (e) => e is TimeoutException, // only catch timeouts here
)

Mixing await and .catchError is fine, but pick one style per chain for readability — try/catch with await is usually clearer.

Stream errors: different from futures

A Future fails once. A Stream can deliver multiple error events interleaved with data — and, crucially, an error doesn't necessarily end the stream. This changes how you handle them.

With await for → use try/catch

An error event in a stream is thrown out of the await for, so wrap the loop:

Future<void> consume(Stream<int> stream) async {
  try {
    await for (final value in stream) {
      print('data: $value');
    }
    print('done');                 // runs on the done event
  } catch (e) {
    print('stream error: $e');     // an error event lands here
  }
}

⚠️ But note: when an error is thrown out of await for, the loop terminates — you stop consuming the rest of the stream. If you want to keep going after an error, don't use await for; use .listen() with an onError callback (below), or filter errors out first with .handleError().

With .listen() → use the onError callback

.listen() separates the three event types into three callbacks, and cancelOnError decides whether one error stops the subscription:

stream.listen(
  (value) => print('data: $value'),
  onError: (e, stack) => print('error: $e'), // handle each error event
  onDone: () => print('done'),
  cancelOnError: false, // false = keep listening after an error (default)
);

| | Future | Stream | | --- | --- | --- | | Failures | one, then it's settled | possibly many error events | | Ends on error? | yes (it's done) | not necessarily (depends on cancelOnError) | | Catch with await | try/catch around await | try/catch around await for (loop ends on error) | | Catch with callbacks | .catchError() | .listen(onError: ...) / .handleError() |

handleError — filter errors mid-pipeline

handleError() intercepts errors in the stream pipeline, optionally letting valid data continue:

numbers
    .map((n) => 100 ~/ n)              // throws on n == 0
    .handleError((e) => print('skip: $e')) // swallow the error, keep the stream alive
    .listen((v) => print('value: $v'));

The thing that bites everyone: unhandled async errors

An error in a future that nobody is awaiting or catching doesn't crash at the throw site — it becomes an unhandled asynchronous error that bubbles up later, often to the top-level zone (more on zones in Part 9). In Flutter it may print a red error to the console or get reported to FlutterError.onError, but it won't be caught by your local try/catch.

void main() {
  // ❌ This throws, but no one awaits/catches it → unhandled async error.
  Future.delayed(const Duration(seconds: 1), () => throw 'boom');

  // Even adding try/catch around the line above wouldn't help —
  // the error happens LATER, after main()'s try block is long gone.
}

Defenses:

1. Always await or .catchError every future you create. Turn on the unawaited_futures lint.
2. For deliberate fire-and-forget, still attach a handler or use unawaited(...) and accept the risk consciously.
3. As a safety net, run your app inside runZonedGuarded (or set FlutterError.onError / PlatformDispatcher.instance.onError) to catch anything that slips through — the subject of Part 9.

// A last-resort catch-all for truly uncaught async errors:
import 'dart:async';

void main() {
  runZonedGuarded(() {
    runApp(const MyApp());
  }, (error, stack) {
    log('UNCAUGHT: $error\n$stack'); // report to Crashlytics/Sentry, etc.
  });
}

Best practices

1. Await inside the try. No await, no catch.
2. Catch specific types with on Type catch before a generic catch.
3. rethrow, don't throw e, when re-propagating — preserve the stack.
4. Translate low-level errors into meaningful app errors at boundaries (network → "couldn't load").
5. Clean up in finally / whenComplete — spinners, files, locks.
6. Decide stream error policy: stop on first error (await for or cancelOnError: true) vs continue (onError / handleError).
7. Never leave a future unhandled. Lints + a top-level runZonedGuarded/FlutterError.onError safety net.

Practice Challenges

Challenge 1 — Fix the silent failure. Make this actually catch the error.

Future<void> run() async {
  try {
    fetch(); // throws after a delay
  } catch (e) {
    print('handled: $e');
  }
}

Future<void> run() async {
  try {
    await fetch(); // the await is what lets catch see the error
  } catch (e) {
    print('handled: $e');
  }
}

Challenge 2 — Type-specific handling. Handle TimeoutException and FormatException differently, with a catch-all fallback.

Future<void> load() async {
  try {
    await doWork();
  } on TimeoutException {
    print('try again later');
  } on FormatException catch (e) {
    print('bad data: $e');
  } catch (e, s) {
    log('unexpected', e, s);
    rethrow;
  }
}

Challenge 3 — Preserve the stack. Why is rethrow better than throw e here?

} catch (e) {
  metrics.increment('failure');
  throw e;
}

Challenge 4 — Keep the stream alive. A stream of divisors occasionally divides by zero. Print valid results and skip errors without stopping the stream.

Stream.fromIterable([2, 0, 4])
    .map((n) => 100 ~/ n)                  // throws on 0
    .handleError((e) => print('skipped: $e'))
    .listen((v) => print('ok: $v'));
// ok: 50  /  skipped: ...  /  ok: 25

Challenge 5 — Catch the uncatchable. This error never hits the try. Explain and give the right safety net.

void main() {
  try {
    Future.error('async boom');
  } catch (e) {
    print('caught');
  }
}

Questions to test yourself

Q1 (basic). Complete the rule: "try/catch only catches an async error if ___."

Q2 (basic). Which Future callbacks correspond to catch and finally?

Q3 (intermediate). How does error handling for a Stream differ fundamentally from a Future?

Q4 (intermediate). Why prefer rethrow over throw e when re-propagating a caught error?

Q5 (advanced). Using await for, an error event occurs mid-stream. What happens to the loop, and what would you use instead to keep consuming?

Q6 (advanced). What is an "unhandled async error", why can't a local try/catch stop it, and what's the global safety net?

Wrapping up

Async errors travel through time, so handling them takes a few firm rules:

• No await, no catch — await the failing future inside the try.
• try/catch/finally (with await) mirrors .then/.catchError/.whenComplete.
• Use on Type catch for specific errors and rethrow to preserve stack traces.
• Streams differ: multiple error events, may not end on error — choose await for (stops on error) vs .listen(onError:)/.handleError() (continues).
• Unhandled async errors bypass local try/catch; guard every future and add a top-level runZonedGuarded/FlutterError.onError safety net.

That safety net — and the surprisingly deep machinery that makes it possible — runs on a concept we've referenced repeatedly: the zone. But before zones, there's the topic that finally gives us true parallelism for the CPU-bound work async can't help with. Part 8 is Isolates — real multithreading in Dart.