Flutter throws an unhandled exception because a binding was used before it was ready
Unhandled 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.
Fix it fast
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.dart2Match what you see, then jump to its fix
- 1
Unhandled 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
Cannot set the method call handler before the binary messenger has been initializedsetMethodCallHandler runs before the binding existsFix - 3
A plugin call fails only inside a function you passed to Isolate.spawnA plugin is called inside Isolate.spawnFix - 4
Zone mismatch. The Flutter bindings were initialized in a different zone than is now being used.ensureInitialized and runApp run in different zonesFix
- 1
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.dart2Fix
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 runConfirmed by api.flutter.dev
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 runConfirmed by raw.githubusercontent.com
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 runConfirmed by docs.flutter.dev
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.dart2Fix
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 runConfirmed by raw.githubusercontent.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
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 fixMobile apps
AudioCache has no play method after updating audioplayers
The method 'play' isn't defined for the type 'AudioCache'.
Since audioplayers 1.0, AudioCache only turns asset files into local files and caches them.
2 causes, each with a fixMobile apps
Flutter Bloc throws that emit was called after the event handler completed
emit was called after an event handler completed normally.
Each on<Event> handler gets its own Emitter, and it stops working the moment the handler's returned Future completes.
2 causes, each with a fixMobile apps
analysis_options.yaml: the URI it includes can't be found
include_file_not_found
The analyzer reports include_file_not_found when the file named after include: in analysis_options.yaml does not resolve.
2 causes, each with a fixMobile apps
Dart error: the body might complete normally and return null for a non-nullable type
body_might_complete_normally
Dart found a path through your function or callback that reaches the closing brace without a return.
3 causes, each with a fixMobile apps
Dart throws ConcurrentModificationError while looping over a list
ConcurrentModificationError
Dart throws this when a collection changes size while something iterates it.
2 causes, each with a fix