This section covers exception handling and cancellation on exceptions. We already know that a cancelled coroutine throws CancellationException in suspension points and that it is ignored by the coroutines’ machinery. Here we look at what happens if an exception is thrown during cancellation or multiple children of the same coroutine throw an exception.

    Coroutine builders come in two flavors: propagating exceptions automatically ( and actor) or exposing them to users ( and produce). When these builders are used to create a root coroutine, that is not a child of another coroutine, the former builders treat exceptions as uncaught exceptions, similar to Java’s , while the latter are relying on the user to consume the final exception, for example via or receive ( and receive are covered later in section).

    It can be demonstrated by a simple example that creates root coroutines using the GlobalScope:

    The output of this code is (with ):

    1. Throwing exception from launch
    2. Exception in thread "DefaultDispatcher-worker-2 @coroutine#2" java.lang.IndexOutOfBoundsException
    3. Joined failed job
    4. Throwing exception from async
    5. Caught ArithmeticException

    It is possible to customize the default behavior of printing uncaught exceptions to the console. CoroutineExceptionHandler context element on a root coroutine can be used as generic catch block for this root coroutine and all its children where custom exception handling may take place. It is similar to ). 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.

    On JVM it is possible to redefine global exception handler for all coroutines by registering CoroutineExceptionHandler via . Global exception handler is similar to Thread.defaultUncaughtExceptionHandler) which is used when no more specific handlers are registered. On Android, uncaughtExceptionPreHandler is installed as a global coroutine exception handler.

    CoroutineExceptionHandler is invoked only on uncaught exceptions — exceptions that were not handled in any other way. In particular, all children coroutines (coroutines created in the context of another ) 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. In addition to that, async builder always catches all exceptions and represents them in the resulting object, so its CoroutineExceptionHandler has no effect either.

    Coroutines running in supervision scope do not propagate exceptions to their parent and are excluded from this rule. A further Supervision section of this document gives more details.

    1. import kotlinx.coroutines.*
    3. fun main() = runBlocking {
    4. //sampleStart
    5.     val handler = CoroutineExceptionHandler { _, exception -> 
    6.         println("CoroutineExceptionHandler got $exception") 
    7.     }
    8.     val job = GlobalScope.launch(handler) { // root coroutine, running in GlobalScope
    9.         throw AssertionError()
    10.     }
    11.     val deferred = GlobalScope.async(handler) { // also root, but async instead of launch
    12.         throw ArithmeticException() // Nothing will be printed, relying on user to call deferred.await()
    13.     }
    14.     joinAll(job, deferred)
    15. //sampleEnd    
    16. }

    You can get the full code .

    The output of this code is:

    1. CoroutineExceptionHandler got java.lang.AssertionError

    Cancellation is closely related to exceptions. Coroutines internally use CancellationException for cancellation, these exceptions are ignored by all handlers, so they should be used only as the source of additional debug information, which can be obtained by catch block. When a coroutine is cancelled using Job.cancel, it terminates, but it does not cancel its parent.

    1. import kotlinx.coroutines.*
    3. fun main() = runBlocking {
    4. //sampleStart
    5.     val job = launch {
    6.         val child = launch {
    7.             try {
    8.                 delay(Long.MAX_VALUE)
    9.             } finally {
    10.                 println("Child is cancelled")
    11.             }
    12.         }
    13.         yield()
    14.         println("Cancelling child")
    15.         child.cancel()
    16.         child.join()
    17.         yield()
    18.     }
    19.     job.join()
    20. //sampleEnd    
    21. }

    The output of this code is:

    2. Child is cancelled
    3. Parent is not cancelled

    If a coroutine encounters an exception other than CancellationException, it cancels its parent with that exception. This behaviour cannot be overridden and is used to provide stable coroutines hierarchies for . CoroutineExceptionHandler implementation is not used for child coroutines.

    The original exception is handled by the parent only when all its children terminate, which is demonstrated by the following example.

    You can get the full code .

    The output of this code is:

    1. Second child throws an exception
    2. Children are cancelled, but exception is not handled until all children terminate
    3. The first child finished its non cancellable block
    4. CoroutineExceptionHandler got java.lang.ArithmeticException

    When multiple children of a coroutine fail with an exception, the general rule is “the first exception wins”, so the first exception gets handled. All additional exceptions that happen after the first one are attached to the first exception as suppressed ones.

    1. import kotlinx.coroutines.*
    2. import java.io.*
    4. fun main() = runBlocking {
    5.     val handler = CoroutineExceptionHandler { _, exception ->
    6.         println("CoroutineExceptionHandler got $exception with suppressed ${exception.suppressed.contentToString()}")
    7.     }
    8.     val job = GlobalScope.launch(handler) {
    9.         launch {
    10.             try {
    11.                 delay(Long.MAX_VALUE) // it gets cancelled when another sibling fails with IOException
    12.             } finally {
    13.                 throw ArithmeticException() // the second exception
    14.             }
    15.         }
    16.         launch {
    17.             delay(100)
    18.             throw IOException() // the first exception
    19.         }
    20.         delay(Long.MAX_VALUE)
    21.     }
    22.     job.join()  
    23. }

    You can get the full code here.

    Note: This above code will work properly only on JDK7+ that supports suppressed exceptions

    The output of this code is:

    1. CoroutineExceptionHandler got java.io.IOException with suppressed [java.lang.ArithmeticException]

    Note that this mechanism currently only works on Java version 1.7+. The JS and Native restrictions are temporary and will be lifted in the future.

    Cancellation exceptions are transparent and are unwrapped by default:

    1. import kotlinx.coroutines.*
    2. import java.io.*
    4. fun main() = runBlocking {
    5. //sampleStart
    6.     val handler = CoroutineExceptionHandler { _, exception ->
    7.         println("CoroutineExceptionHandler got $exception")
    8.     }
    9.     val job = GlobalScope.launch(handler) {
    10.         val inner = launch { // all this stack of coroutines will get cancelled
    11.             launch {
    12.                 launch {
    13.                     throw IOException() // the original exception
    14.                 }
    15.             }
    16.         }
    17.         try {
    18.             inner.join()
    19.         } catch (e: CancellationException) {
    20.             println("Rethrowing CancellationException with original cause")
    21.             throw e // cancellation exception is rethrown, yet the original IOException gets to the handler  
    22.     }
    24. //sampleEnd    
    25. }

    The output of this code is:

    1. Rethrowing CancellationException with original cause
    2. CoroutineExceptionHandler got java.io.IOException

    As we have studied before, cancellation is a bidirectional relationship propagating through the whole hierarchy of coroutines. Let us take a look at the case when unidirectional cancellation is required.

    A good example of such a requirement is a UI component with the job defined in its scope. If any of the UI’s child tasks have failed, it is not always necessary to cancel (effectively kill) the whole UI component, but if UI component is destroyed (and its job is cancelled), then it is necessary to fail all child jobs as their results are no longer needed.

    Another example is a server process that spawns multiple child jobs and needs to supervise their execution, tracking their failures and only restarting the failed ones.

    Supervision job

    The SupervisorJob can be used for these purposes. It is similar to a regular with the only exception that cancellation is propagated only downwards. This can easily be demonstrated using the following example:

    You can get the full code here.

    The output of this code is:

    1. The first child is failing
    2. The first child is cancelled: true, but the second one is still active
    3. Cancelling the supervisor
    4. The second child is cancelled because the supervisor was cancelled

    Supervision scope

    Instead of coroutineScope, we can use for scoped concurrency. It propagates the cancellation in one direction only and cancels all its children only if it failed itself. It also waits for all children before completion just like coroutineScope does.

    1. import kotlin.coroutines.*
    2. import kotlinx.coroutines.*
    4. fun main() = runBlocking {
    5.     try {
    6.         supervisorScope {
    7.             val child = launch {
    8.                 try {
    9.                     println("The child is sleeping")
    10.                     delay(Long.MAX_VALUE)
    11.                 } finally {
    12.                     println("The child is cancelled")
    13.                 }
    14.             }
    15.             // Give our child a chance to execute and print using yield 
    16.             yield()
    17.             println("Throwing an exception from the scope")
    18.             throw AssertionError()
    19.         }
    20.     } catch(e: AssertionError) {
    21.         println("Caught an assertion error")
    22.     }
    23. }

    You can get the full code .

    The output of this code is:

    1. The child is sleeping
    2. Throwing an exception from the scope
    3. The child is cancelled
    4. Caught an assertion error

    Exceptions in supervised coroutines

    Another crucial difference between regular and supervisor jobs is exception handling. Every child should handle its exceptions by itself via the exception handling mechanism. This difference comes from the fact that child’s failure does not propagate to the parent. It means that coroutines launched directly inside the do use the CoroutineExceptionHandler that is installed in their scope in the same way as root coroutines do (see the section for details).

    1. import kotlin.coroutines.*
    2. import kotlinx.coroutines.*
    4. fun main() = runBlocking {
    5.     val handler = CoroutineExceptionHandler { _, exception -> 
    6.         println("CoroutineExceptionHandler got $exception") 
    7.     }
    8.     supervisorScope {
    9.         val child = launch(handler) {
    10.             println("The child throws an exception")
    11.             throw AssertionError()
    12.         }
    13.         println("The scope is completing")
    14.     }
    15.     println("The scope is completed")
    16. }

    You can get the full code here.

    1. The scope is completing
    2. The child throws an exception
    3. CoroutineExceptionHandler got java.lang.AssertionError