Maaz Zindani

Loading the index…

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

Flutter throws an unhandled exception because a binding was used before it was ready

ErrorUnhandled Exception: Binding has not yet been initialized.

Short answer

Flutter's bindings are created by runApp or by WidgetsFlutterBinding.ensureInitialized(). Any plugin or platform channel touched earlier, in main() or in a static field, fails. Call ensureInitialized() as the first line of main(). In a spawned isolate, pass the root isolate token. Run it in the same zone as runApp.

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

Fix it fast

  1. 1Find out which cause you have

    Read the stack trace under the exception and find the first line that is your own code. That line is the call that ran before the binding existed, and it decides which cause applies. Look at what runs in main() before runApp.

    flutter run -v
    grep -n "runApp\|ensureInitialized\|runZonedGuarded" lib/main.dart
  2. 2Match what you see, then jump to its fix

    1. 1Unhandled Exception: Binding has not yet been initialized, pointing at a line in main() above runAppA plugin or channel is used in main() before runAppFix
    2. 2Cannot set the method call handler before the binary messenger has been initializedsetMethodCallHandler runs before the binding existsFix
    3. 3A plugin call fails only inside a function you passed to Isolate.spawnA plugin is called inside Isolate.spawnFix
    4. 4Zone mismatch. The Flutter bindings were initialized in a different zone than is now being used.ensureInitialized and runApp run in different zonesFix

What does the error look like?

  • Unhandled Exception: Binding has not yet been initialized.
  • Cannot set the method call handler before the binary messenger has been initialized.
  • This happens when you call setMethodCallHandler() before the WidgetsFlutterBinding has been initialized.
  • Zone mismatch.

Cause 1 of 4

A plugin or channel is used in main() before runApp

1Check

Find awaited plugin calls (Firebase.initializeApp, SharedPreferences.getInstance, path_provider, your own MethodChannel) that sit before runApp. Plugins talk to the platform through channels, and channels need the binding. runApp creates it, so anything earlier has no binding yet.

sed -n '1,40p' lib/main.dart

2Fix

Make main async and call WidgetsFlutterBinding.ensureInitialized() as its first statement. It returns the existing binding or creates one.

import 'package:flutter/widgets.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // plugin setup that needs channels goes after this line
  runApp(const MyApp());
}

3Verify

Run the app. The exception no longer appears at startup.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 2 of 4

setMethodCallHandler runs before the binding exists

1Check

Look for a MethodChannel whose setMethodCallHandler is called from a top-level variable, a static field or a constructor that runs before runApp.

grep -rn "setMethodCallHandler" lib/

2Fix

Either initialize the binding before that call, or give the channel its own BinaryMessenger so it does not depend on the default one.

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  const channel = MethodChannel('app/native');
  channel.setMethodCallHandler((call) async => null);
  runApp(const MyApp());
}

3Verify

Start the app and confirm the assertion is gone.

flutter run

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 4

A plugin is called inside Isolate.spawn

1Check

A spawned isolate is not the root isolate, so it has no channel connection of its own. Check which isolate runs the failing plugin call.

grep -rnE "Isolate.spawn|compute[(]" lib/

2Fix

Read RootIsolateToken.instance on the root isolate, send it to the new isolate, and call BackgroundIsolateBinaryMessenger.ensureInitialized with it before using any plugin there.

void _isolateMain(RootIsolateToken token) async {
  BackgroundIsolateBinaryMessenger.ensureInitialized(token);
  final prefs = await SharedPreferences.getInstance();
  print(prefs.getBool('isDebug'));
}

void main() {
  final token = RootIsolateToken.instance!;
  Isolate.spawn(_isolateMain, token);
}

3Verify

The isolate finishes without the exception and prints its value.

flutter run

Confirmed by docs.flutter.dev

Did this fix it?

Cause 4 of 4

ensureInitialized and runApp run in different zones

1Check

Look for runZonedGuarded or Zone.run around only part of main(): ensureInitialized outside the zone, runApp inside it, or the other way round.

grep -nE "runZonedGuarded|Zone" lib/main.dart

2Fix

Call both in the same zone: put ensureInitialized inside the zone callback, next to runApp.

void main() {
  runZonedGuarded(() {
    WidgetsFlutterBinding.ensureInitialized();
    runApp(const MyApp());
  }, (error, stack) {
    debugPrint('$error');
  });
}

3Verify

Restart the app. The Zone mismatch message is gone.

flutter run

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Keep WidgetsFlutterBinding.ensureInitialized() as the first line of every main() that is async or touches a plugin.
  • Never open channels or create plugin clients in top-level variables; create them after the binding exists.
  • Put zone setup in one place so ensureInitialized and runApp share it.
  • Pass the root isolate token to every isolate that uses plugins.

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

Mobile apps

Flutter throws MissingPluginException for a plugin method

MissingPluginException(No implementation found for method getAll on channel plugins.flutter.io/shared_preferences)

MissingPluginException means Dart called a plugin whose native half is not in the running app.

2 causes, each with a fix

Next step

Want this handled for good?

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