CoroutineExceptionHandler

interface CoroutineExceptionHandler : Element (source)

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
    }
}

Implementation details

By default, when no handler is installed, uncaught exception are handled in the following way:

CoroutineExceptionHandler can be invoked from an arbitrary thread.

Types

Key

companion object Key : Key<CoroutineExceptionHandler>

Key for CoroutineExceptionHandler instance in the coroutine context.

Functions

handleException

abstract fun handleException(
    context: CoroutineContext,
    exception: Throwable
): Unit

Handles uncaught exception in the given context. It is invoked if coroutine has an uncaught exception.

Extension Properties

isActive

Returns true when the Job of the coroutine in this context is still active (has not completed and was not cancelled yet).

job

Retrieves the current Job instance from the given CoroutineContext or throws IllegalStateException if no job is present in the context.

Extension Functions

cancel

fun CoroutineContext.cancel(
    cause: CancellationException? = null
): Unit

Cancels Job of this context with an optional cancellation cause. See Job.cancel for details.

cancelChildren

fun CoroutineContext.cancelChildren(
    cause: CancellationException? = null
): Unit

Cancels all children of the Job in this context, without touching the state of this job itself with an optional cancellation cause. See Job.cancel. It does not do anything if there is no job in the context or it has no children.

ensureActive

fun CoroutineContext.ensureActive(): Unit

Ensures that job in the current context is active.