Future.error

Learn Future.error and catchError.

Future.error

A Future can also complete with an error. Future.error(Exception("error")) creates a Future that completes immediately with an error. .then only runs on success; to catch the error you use .catchError.

Example: Future.error(Exception("oops")).then((v) => print(v)).catchError((e) => print(e));. Here .then is skipped, .catchError runs and prints the error. This is the asynchronous version of try/catch. The return of .catchError is a Future; so the rest of the chain is still a Future. To check multiple error types you can also pass a test function.

catchError details

.catchError takes a callback. This callback receives the error as a parameter. .catchError((e) => print("error: \$e")). Since the return is a Future, the rest of the chain is still a Future; so you can recover and continue after an error.

To catch a specific error type you can pass a test parameter: .catchError((e) => print(e), test: (e) => e is FormatException). This catches only FormatException errors; others propagate up the chain. This is the asynchronous counterpart of the on clause. To run cleanup code on error there is also .whenComplete; the asynchronous counterpart of finally.

Exercise Your turn: catch the error

Create a Future that fails with Future.error(Exception("oops")). Write the success path with .then((v) => print(v)) and print the error with .catchError((e) => print(e)). The error reaches the screen.

Show example solution

void main() {
  Future.error(Exception("oops")).then((v) => print(v)).catchError((e) => print(e));
}

Test yourself

When does .then run?
```
Future.error(Exception("error"))
  .then((v) => print(v))
  .catchError((e) => print(e));
```
- Only on error
- Only on success
- Never
- Always
Show answer

Only on success — then runs only on success.

catchError

Future.error(Exception("oops")).then((v) => print(v)).____((e) => print(e));

Show answer

Future.error(Exception("oops")).then((v) => print(v)).catchError((e) => print(e));

Match Future.error

Future.error

completes with an error
.then

runs on success
.catchError

catches the error
.whenComplete

always runs

Next lesson: Future.wait

We Are Enhancing Your Experience

Cookie Preferences

Strictly Necessary Cookies

Analytical Cookies