Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

A Dart try/catch block never runs even though the code throws

ErrorThe catch block never runs

Short answer

A try block only catches errors from a future if the future is awaited inside it. Without await, the try block only holds the future and has nothing to catch. Add await in an async function, and register PlatformDispatcher.instance.onError for what still escapes.

  • Applies to Dart 3, Flutter 3.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Turn on the two Dart lints that flag futures nobody waits for. Every warning they print is a place where a catch cannot work.

    # analysis_options.yaml
    linter:
      rules:
        - unawaited_futures
        - discarded_futures
  2. 2Match what you see, then jump to its fix

    1. 1unawaited_futures warns on the line, or the printed value is Instance of '_Future<...>'The future is not awaited inside the try blockFix
    2. 2The error shows in the console as unhandled, and it is not reported by FlutterError.onErrorThe error is raised outside any Flutter callback and no try block wraps itFix

What does the error look like?

  • The catch block never runs
  • Instance of '_Future<String>' is printed instead of the value

Cause 1 of 2

The future is not awaited inside the try block

1Check

A failed async operation completes its future with an error. Dart's guide says to await the future inside the try block so that the error is caught there; without await you only hold the future.

dart analyze

2Fix

Make the function async and put await in front of the call inside the try block.

Future<void> load() async {
  try {
    await api.fetchOrders();   // await keeps the error inside try
  } catch (e, st) {
    debugPrint('failed: $e');
  }
}

3Verify

Make the call fail on purpose, for example with no network, and watch the catch block run.

flutter run

Confirmed by dart.dev

Did this fix it?

Cause 2 of 2

The error is raised outside any Flutter callback and no try block wraps it

1Check

Flutter documents that errors with no Flutter callback on the stack skip FlutterError.onError and go to PlatformDispatcher. Its own example is an async onPressed calling a plugin.

grep -rn "PlatformDispatcher\|FlutterError.onError" lib

2Fix

Register the dispatcher hook in main() so these errors are handled, logged or sent to your crash service. Return true to mark an error as handled.

void main() {
  PlatformDispatcher.instance.onError = (error, stack) {
    debugPrint('uncaught: $error');
    return true;
  };
  runApp(const MyApp());
}

3Verify

Trigger the failing call and see the message from your handler instead of an unhandled exception.

flutter run

Confirmed by docs.flutter.dev

Did this fix it?

How do I stop it coming back?

  • Keep unawaited_futures and discarded_futures enabled, and treat their warnings as bugs.
  • Every function that does async work and can fail should return Future and be awaited by its caller.
  • Install the global error hooks early in main(), so nothing escapes silently in release builds.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.