CoroutineExceptionHandler

An optional element in the coroutine context to handle uncaught exceptions.

Normally, uncaught exceptions can only result from root coroutines created using the launch builder. All children coroutines (coroutines created in the context of another Job) delegate handling of their exceptions to their parent coroutine, which also delegates to the parent, and so on until the root, so the CoroutineExceptionHandler installed in their context is never used. Coroutines running with SupervisorJob do not propagate exceptions to their parent and are treated like root coroutines. A coroutine that was created using async always catches all its exceptions and represents them in the resulting Deferred object, so it cannot result in uncaught exceptions.

Handling coroutine exceptions

CoroutineExceptionHandler is a last-resort mechanism for global "catch all" behavior. You cannot recover from the exception in the CoroutineExceptionHandler. The coroutine had already completed with the corresponding exception when the handler is called. Normally, the handler is used to log the exception, show some kind of error message, terminate, and/or restart the application.

If you need to handle exception in a specific part of the code, it is recommended to use try/catch around the corresponding code inside your coroutine. This way you can prevent completion of the coroutine with the exception (exception is now caught), retry the operation, and/or take other arbitrary actions:

scope.launch { // launch child coroutine in a scope
    try {
         // do something
    } catch (e: Throwable) {
         // handle exception
    }
}

Uncaught exceptions with no handler

When no handler is installed, exception are handled in the following way:

• If exception is CancellationException, it is ignored, as these exceptions are used to cancel coroutines.

• Otherwise, if there is a Job in the context, then Job.cancel is invoked.

• Otherwise, as a last resort, the exception is processed in a platform-specific manner:

• On JVM, all instances of CoroutineExceptionHandler found via ServiceLoader, as well as the current thread's Thread.uncaughtExceptionHandler, are invoked.

• On Native, the whole application crashes with the exception.

• On JS, the exception is logged via the Console API.

CoroutineExceptionHandler can be invoked from an arbitrary thread.