Exceptions, Errors and asserts in Dart

Feb 19 · 3 min read

What’s the difference?

Photo by Sarah Kilian on Unsplash


  • An Error, on the other hand, is for developers who are using your code. You throw an Error to let them know that they are using your code wrong. As the developer using an API, you shouldn't catch errors. You should let them crash your app. Let the crash be a message to you that you need to go find out what you're doing wrong.
  • An assert is similar to an Error in that it is for reporting bad states that should never happen. The difference is that asserts are only checked in debug mode. They are completely ignored in production mode.

Read more on the difference between Exception and Error here.

Next, here are a few examples to see how each is used in the Flutter source code.

Example of throwing an Exception

Future<T?> _invokeMethod<T>(String method, { required bool missingOk, dynamic arguments }) async {
assert(method != null);
final ByteData? result = await binaryMessenger.send(
codec.encodeMethodCall(MethodCall(method, arguments)),
if (result == null) {
if (missingOk) {
return null;
throw MissingPluginException('No implementation found for method $method on channel $name');
return codec.decodeEnvelope(result) as T;

The MissingPluginException here is a planned bad state that might occur. If it happens, users of the platform channel API need to be ready to handle that.

Example of throwing an Error

TargetPlatform _currentHostPlatform(Platform platform) {
if (platform.isMacOS) {
return TargetPlatform.darwin_x64;
if (platform.isLinux) {
return TargetPlatform.linux_x64;
if (platform.isWindows) {
return TargetPlatform.windows_x64;
throw UnimplementedError('Host OS not supported.');

First every possibility is exhausted and then the error is thrown. This should be theoretically impossible. But if it is thrown, then it is either a sign to the API user that you’re using it wrong, or a sign to the API maintainer that they need to handle another case.

Example of using asserts

@required this.builder,
bool opaque = false,
bool maintainState = false,
}) : assert(builder != null),
assert(opaque != null),
assert(maintainState != null),
_opaque = opaque,
_maintainState = maintainState;

The pattern in the Flutter source code is to use asserts liberally in the initializer list in constructors. They are far more common that Errors.


I originally published this article as a Stack Overflow answer here.

Flutter Community

Articles and Stories from the Flutter Community

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store