CoroutineExceptionHandler not executed when provided as launch context

Question

When I run this:

fun f() = runBlocking {
    val eh = CoroutineExceptionHandler { _, e -> trace("exception handler: $e") }
    val j1 = launch(eh) {
        trace("launched")
        delay(1000)
        throw RuntimeException("error!")
    }
    trace("joining")
    j1.join()
    trace("after join")
}
f()

This is output:

[main @coroutine#1]: joining
[main @coroutine#2]: launched
java.lang.RuntimeException: error!
    at ExceptionHandling$f9$1$j1$1.invokeSuspend(ExceptionHandling.kts:164)
    at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:32)
    at kotlinx.coroutines.ResumeModeKt.resumeMode(ResumeMode.kt:67)

According to the documentation for CoroutineExceptionHandler, the eh handler I provided should be executed. But it's not. Why is that?

Answer 1

I believe the answer lies in this section from the official coroutines docs:

If a coroutine encounters 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 structured concurrency which do not depend on CoroutineExceptionHandler implementation. The original exception is handled by the parent when all its children terminate.

This also a reason why, in these examples, CoroutineExceptionHandler is always installed to a coroutine that is created in GlobalScope. It does not make sense to install an exception handler to a coroutine that is launched in the scope of the main runBlocking, since the main coroutine is going to be always cancelled when its child completes with exception despite the installed handler.

(emphasis mine)

What's described here applies not just to runBlocking and GlobalScope, but any non-top-level coroutine builder and custom scope.

To illustrate (using kotlinx.coroutines v1.0.0):

fun f() = runBlocking {
    val h1 = CoroutineExceptionHandler { _, e ->
        trace("handler 1 e: $e")
    }
    val h2 = CoroutineExceptionHandler { _, e ->
        trace("handler 2 e: $e")
    }
    val cs = CoroutineScope(newSingleThreadContext("t1"))
    trace("launching j1")
    val j1 = cs.launch(h1) {
        delay(1000)
        trace("launching j2")
        val j2 = launch(h2) {
            delay(500)
            trace("throwing exception")
            throw RuntimeException("error!")
        }
        j2.join()
    }
    trace("joining j1")
    j1.join()
    trace("exiting f")
}
f()

Output:

[main @coroutine#1]: launching j1
[main @coroutine#1]: joining j1
[t1 @coroutine#2]: launching j2
[t1 @coroutine#3]: throwing exception
[t1 @coroutine#2]: handler 1 e: java.lang.RuntimeException: error!
[main @coroutine#1]: exiting f

Note that handler h1 is executed, but h2 isn't. This is analogous to the handler on GlobalScope#launch executing, but not the handler provided to any launch inside runBlocking.

TLDR

Handlers provided to non-root coroutines of a scope will be ignored. A handler provided to the root coroutine will be executed.

As correctly pointed out by Marko Topolnik in the comments below, the above generalization only applies to coroutines created by launch. Those created by async or produce will always ignore all handlers.

Answer 2

What is your kotlinx.coroutines version? Since 0.26.0 standalone launch builder is now deprecated and You should be using GlobalScope.launch instead.

I tried your sample and after that change it worked.

Kotlinx.coroutines changelog