The Flutter framework catches errors that occur during callbacks triggered by the framework itself, including errors encountered during the build, layout, and paint phases. Errors that don't occur within Flutter's callbacks can't be caught by the framework, but you can handle them by setting up an error handler on thePlatformDispatcher.

All errors caught by Flutter are routed to theFlutterError.onError handler. By default, this callsFlutterError.presentError, which dumps the error to the device logs. When running from an IDE, the inspector overrides this behavior so that errors can also be routed to the IDE's console, allowing you to inspect the objects mentioned in the message.

When an error occurs during the build phase, theErrorWidget.builder callback is invoked to build the widget that is used instead of the one that failed. By default, in debug mode this shows an error message in red, and in release mode this shows a gray background.

When errors occur without a Flutter callback on the call stack, they are handled by thePlatformDispatcher's error callback. By default, this only prints errors and does nothing else.

You can customize these behaviors, typically by setting them to values in yourvoid main() function.

Below each error type handling is explained. At the bottom there's a code snippet which handles all types of errors. Even though you can just copy-paste the snippet, we recommend you to first get acquainted with each of the error types.

For example, to make your application quit immediately any time an error is caught by Flutter in release mode, you could use the following handler:

import'dart:io';​import'package:flutter/foundation.dart';import'package:flutter/material.dart';​voidmain(){FlutterError.onError=(details){FlutterError.presentError(details);if(kReleaseMode)exit(1);};runApp(constMyApp());}​// The rest of the `flutter create` code...

This handler can also be used to report errors to a logging service. For more details, see our cookbook chapter forreporting errors to a service.

To define a customized error widget that displays whenever the builder fails to build a widget, useMaterialApp.builder.

classMyAppextendsStatelessWidget{constMyApp({super.key});​@overrideWidgetbuild(BuildContextcontext){returnMaterialApp(builder:(context,widget){Widgeterror=constText('...rendering error...');if(widgetisScaffold||widgetisNavigator){error=Scaffold(body:Center(child:error));}ErrorWidget.builder=(errorDetails)=>error;if(widget!=null)returnwidget;throwStateError('widget is null');},);}}

Consider anonPressed callback that invokes an asynchronous function, such asMethodChannel.invokeMethod (or pretty much any plugin). For example:

OutlinedButton(child:constText('Click me!'),onPressed:()async{constchannel=MethodChannel('crashy-custom-channel');awaitchannel.invokeMethod('blah');},)

IfinvokeMethod throws an error, it won't be forwarded toFlutterError.onError. Instead, it's forwarded to thePlatformDispatcher.

To catch such an error, usePlatformDispatcher.instance.onError.

import'package:flutter/material.dart';import'dart:ui';​voidmain(){MyBackendmyBackend=MyBackend();PlatformDispatcher.instance.onError=(error,stack){myBackend.sendError(error,stack);returntrue;};runApp(constMyApp());}

Say you want to exit application on any exception and to display a custom error widget whenever a widget building fails - you can base your errors handling on next code snippet:

import'package:flutter/material.dart';import'dart:ui';​Future<void>main()async{awaitmyErrorsHandler.initialize();FlutterError.onError=(details){FlutterError.presentError(details);myErrorsHandler.onErrorDetails(details);};PlatformDispatcher.instance.onError=(error,stack){myErrorsHandler.onError(error,stack);returntrue;};runApp(constMyApp());}​classMyAppextendsStatelessWidget{constMyApp({super.key});​@overrideWidgetbuild(BuildContextcontext){returnMaterialApp(builder:(context,widget){Widgeterror=constText('...rendering error...');if(widgetisScaffold||widgetisNavigator){error=Scaffold(body:Center(child:error));}ErrorWidget.builder=(errorDetails)=>error;if(widget!=null)returnwidget;throwStateError('widget is null');},);}}