Futures and Error Handling

This article covers the subject of error handling when dealing with Futures.
If you are unfamiliar with the general concepts behind Futures, we
recommend you first read
Asynchronous Programming: Futures.

Introduction

A Future represents a deferred computation. Receivers of a Future can register
callbacks that handle the value or the error that completes a Future:

myFunc().then(processValue)
.catchError(handleError);

The registered callbacks fire based on the following rules: then()’s
callback fires if it is invoked on a Future that completes with a value;
catchError()’s callback fires if it is invoked on a Future that completes
with an error.

In the example above, if myFunc()’s Future completes with a value,
then()’s callback fires. If no new error is produced within then(),
catchError()’s callback does not fire. On the other hand, if myFunc()
completes with an error, then()’s callback does not fire, and
catchError()’s callback does.

Examples of using then() with catchError()

Chained then() and catchError() invocations are a common pattern when
dealing with Futures, and can be thought of as the rough equivalent of
try-catch blocks.

The next few sections give examples of this pattern.

catchError() as a comprehensive error handler

The following example deals with throwing an exception from within then()’s
callback and demonstrates catchError()’s versatility as an error handler:

If myFunc()’s Future completes with a value, then()’s callback fires. If
code within then()’s callback throws (as it does in the example above),
then()’s Future completes with an error. That error is handled by
catchError().

If myFunc()’s Future completes with an error, then()’s Future completes
with that error. The error is also handled by catchError().

Regardless of whether the error originated within myFunc() or within
then(), catchError() successfully handles it.

Error handling within then()

For more granular error handling, you can register a second (onError)
callback within then() to handle Futures completed with errors. Here is
then()’s signature:

In the example above, funcThatThrows()’s Future’s error is handled with the
onError callback; anotherFuncThatThrows() causes then()’s Future to
complete with an error; this error is handled by catchError().

In general, implementing two different error handling strategies is not
recommended: register a second callback only if there is a compelling reason
to catch the error within then().

Errors in the middle of a long chain

It is common to have a succession of then() calls, and catch errors
generated from any part of the chain using catchError():

In the code above, one()’s Future completes with a value, but two()’s
Future completes with an error. When then() is invoked on a Future that
completes with an error, then()’s callback does not fire. Instead,
then()’s Future completes with the error of its receiver. In our example,
this means that after two() is called, the Future returned by every
subsequent then()completes with two()’s error. That error is finally
handled within catchError().

Handling specific errors

What if we want to catch a specific error? Or catch more than one error?

catchError() takes an optional named argument, test, that
allows us to query the kind of error thrown.

Consider handleAuthResponse(params), a function that authenticates a user
based on the params provided, and redirects the user to an appropriate URL.
Given the complex workflow, handleAuthResponse() could generate various
errors and exceptions, and you should handle them differently. Here’s
how you can use test to do that:

Async try-catch-finally using whenComplete()

If then().catchError() mirrors a try-catch, whenComplete() is the
equivalent of ‘finally’. The callback registered within whenComplete() is
called when whenComplete()’s receiver completes, whether it does so with a
value or with an error:

In the code below, then()’s Future completes with an error, which is now
handled by catchError(). Because catchError()’s Future completes with
someObject, whenComplete()’s Future completes with that same object.

Potential problem: failing to register error handlers early

It is crucial that error handlers are installed before a Future completes:
this avoids scenarios where a Future completes with an error, the error
handler is not yet attached, and the error accidentally propagates. Consider
this code:

Functions that return Futures should almost always emit their errors in the
future. Since we do not want the caller of such functions to have to
implement multiple error-handling scenarios, we want to prevent any synchronous
errors from leaking out. Consider this code:

Two functions in that code could potentially throw synchronously:
obtainFileName() and parseFileData(). Because parseFileData() executes
inside a then() callback, its error does not leak out of the function.
Instead, then()’s Future completes with parseFileData()’s error, the error
eventually completes parseAndRead()’s Future, and the error can be
successfully handled by catchError().

But obtainFileName() is not called within a then() callback; if it
throws, a synchronous error propagates:

If the callback returns a non-Future value, Future.sync()’s Future completes
with that value. If the callback throws (as it does in the example
above), the Future completes with an error. If the callback itself returns a
Future, the value or the error of that Future completes Future.sync()’s
Future.

With code wrapped within Future.sync(), catchError() can handle all errors: