CodeBlanks Logo Icon CodeBlanks
Login Register

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.

Practice 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.

Starter code

main.dart
void main() {
  // Create a Future with Future.error
  // .then for success
  // .catchError prints the error
}

Sample solution

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

Expected output

Exception: oops

Questions and answers

Review the lesson questions together with their answers. To test yourself, solve the lesson interactively.

1 When does .then run?

main.dart
Future.error(Exception("error"))
  .then((v) => print(v))
  .catchError((e) => print(e));
  • Only on error
  • Only on success Correct answer
  • Never
  • Always

Explanation: then runs only on success.

2 catchError

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

Explanation: catchError catches the error.

3 Match Future.error

Term Meaning
Future.error completes with an error
.then runs on success
.catchError catches the error
.whenComplete always runs

All lessons in Beginner

1 Dart basics

  1. What is Dart?
  2. Your first program
  3. dart run
  4. Comments
  5. String interpolation
  6. Summary - Dart basics

2 Variables

  1. var and type
  2. final
  3. const
  4. late
  5. Null safety
  6. Summary - Variables

3 Data types

  1. Integer types
  2. Floating-point types
  3. bool and String
  4. Type inference
  5. dynamic
  6. Summary - Data types

4 Project: Calculator

  1. Project design
  2. Add and subtract
  3. Multiply and divide
  4. Error handling
  5. Putting it together

5 Operators

  1. Arithmetic operators
  2. Assignment operators
  3. Comparison operators
  4. Logical operators
  5. Null-aware operators
  6. Summary - Operators

6 Strings

  1. Creating strings
  2. String interpolation
  3. length and methods
  4. substring
  5. contains and indexOf
  6. Summary - Strings

7 Conditionals

  1. The if statement
  2. else and else if
  3. switch
  4. Pattern matching
  5. Ternary
  6. Summary - Conditionals

8 Loops

  1. The for loop
  2. The while loop
  3. The do-while loop
  4. for-in
  5. break and continue
  6. Summary - Loops

9 Project: Shopping cart

  1. Cart design
  2. Adding items
  3. Calculating totals
  4. Listing the cart
  5. Putting it together

10 Lists

  1. Creating lists
  2. List access
  3. add and remove
  4. length and contains
  5. List methods
  6. Summary - Lists

11 Sets and Maps

  1. Set
  2. Set operations
  3. Map
  4. Map operations
  5. Map iteration
  6. Summary - Sets and Maps

12 Functions

  1. Defining functions
  2. Return values
  3. Arrow functions
  4. Optional parameters
  5. First-class functions
  6. Summary - Functions

13 Null safety in depth

  1. Nullable types
  2. Null-aware operators
  3. The ! operator
  4. late
  5. Null check
  6. Summary - Null safety

14 Class basics

  1. class
  2. Constructor
  3. Instance variables
  4. Methods
  5. this
  6. Summary - Class basics

15 Project: To-do CLI

  1. Task model
  2. Adding tasks
  3. Listing tasks
  4. Completing tasks
  5. Putting it together

16 Advanced string operations

  1. split and join
  2. replace
  3. trim and pad
  4. RegExp
  5. StringBuffer
  6. Summary - Advanced strings

17 Enums

  1. Defining enums
  2. Enum values
  3. Enhanced enums
  4. switch with enum
  5. Enum and patterns
  6. Summary - Enums

18 Exceptions

  1. try/catch
  2. throw
  3. finally
  4. The Exception class
  5. on clause
  6. Summary - Exceptions

19 Async basics

  1. Future
  2. async/await
  3. then
  4. Future.error
  5. Future.wait
  6. Summary - Async basics

20 Beginner final

  1. Project design
  2. Classes
  3. Collections
  4. Error handling
  5. Putting it together