Kotlin Coroutines: Exception Handling Without Surprises

 Mastering propagation rules, supervisor scopes, and building robust exponential backoff retry policies for production apps.

Kotlin Coroutines: Exception Handling Without Surprises

If you’ve been using Kotlin Coroutines for a while, you’ve likely encountered a moment where an app crashed despite having a try-catch block, or perhaps a parent coroutine stayed alive even though its children failed.

Exception handling in coroutines is more than just wrapping code in a block; it’s about understanding the mechanics of propagation and the hierarchy of jobs. Let’s demystify how to handle errors without the “surprises.”

The Golden Rule: Upward vs. Downward Flow

In structured concurrency, exceptions follow a specific traffic pattern that determines how your app recovers (or crashes):

  • Failures propagate UPWARD: When a coroutine fails due to an exception, it notifies its parent. The parent then cancels itself and propagates the cancellation signal to all its other children.
  • Cancellations propagate DOWNWARD: If a parent is cancelled (e.g., the user closes a screen), it cancels all its children. This is considered a “normal” state and doesn’t trigger a crash.

1. launch vs. async: The Reporting Gap

The most common surprise is how exceptions are reported based on the builder used.

launch: The “Fire and Forget”

Exceptions in launch are treated as uncaught. Much like a crash on a standard thread, they will terminate the application immediately unless a CoroutineExceptionHandler is present.

async: The “Silent Footgun”

Exceptions in async are encapsulated in the Deferred result.

Warning: If you fail to call .await(), the exception may be silently ignored and never reported in your logs. However, it will still trigger the cancellation of the parent scope in a regular (non-supervisor) scope.

// If you don't await this, you might never see the error in your logs
val deferred = scope.async {
    throw IllegalStateException("Silent Failure")
}

try {
    deferred.await() // The exception is re-thrown here
} catch (e: Exception) {
    println("Caught: ${e.message}")
}

2. The withContext Exception Behavior

Unlike launch, withContext is a suspending function. Because it blocks the coroutine execution flow (suspends) until it finishes, exceptions are thrown inline, making them much easier to handle with standard try-catch blocks.

try {
    withContext(Dispatchers.IO) {
        throw Exception("Direct Error")
    }
} catch (e: Exception) {
    // This works perfectly because withContext is a suspending call
    println("Caught inline error: ${e.message}")
}

3. SupervisorJob: Isolation in Practice

If you want independent children (e.g., several API calls where one failure shouldn’t kill the others), use a SupervisorJob or supervisorScope. This breaks the upward propagation: a child's failure will not cancel the parent or siblings.

supervisorScope {
    val childA = launch { 
        throw Exception("Task A failed") 
    }

    val childB = launch { 
        delay(100)
        println("Task B is still healthy!") // This will still print
    }
}

4. A “Smart” Retry Policy

In production, you don’t just want to catch errors — you want to recover from them. Below is an idiomatic way to implement a retry mechanism with Exponential Backoff.

/**
 * Retries a [block] with exponential backoff.
 */
suspend fun <T> retryWithBackoff(
    times: Int = 3,
    initialDelay: Long = 100,
    factor: Double = 2.0,
    block: suspend () -> T
): T {
    var currentDelay = initialDelay
    repeat(times - 1) { attempt ->
        try {
            return block() // Success!
        } catch (e: Exception) {
            // Rule 1: Never swallow CancellationException
            if (e is CancellationException) throw e
            
            // Rule 2: Only retry on Network/IO errors. 
            // Do not retry business logic or validation errors.
            if (e !is IOException) throw e 
            
            println("Attempt ${attempt + 1} failed. Retrying in $currentDelay ms...")
        }
        delay(currentDelay)
        currentDelay = (currentDelay * factor).toLong()
    }
    return block() // Final attempt outside try-catch to propagate error if it fails
}

5. Verifying Logic with Unit Tests

Testing coroutine exceptions requires specific tools like runTest to ensure your handlers are actually firing and timeouts are respected.

@Test
fun `test retry logic eventually fails after max attempts`() = runTest {
    var attempts = 0
    // Use assertThrows or try-catch to verify the final failure
    try {
        retryWithBackoff(times = 3) {
            attempts++
            throw IOException("Network down")
        }
    } catch (e: IOException) {
        // Expected
    }
    
    assertEquals(3, attempts)
}

Frequently Asked Questions (FAQs)

Why did my app crash even with a SupervisorJob?

Supervision only stops the cancellation of siblings. It does not handle the exception itself. You still need a try-catch inside the launch or a CoroutineExceptionHandler (CEH) to manage the uncaught error.

What happens if multiple children fail at the same time?

The first exception is handled. Any others that occur during the teardown are attached as “suppressed” exceptions, which you can access via exception.suppressed.

Can I use a CEH with async?

No. async handles exceptions via the returned Deferred object. Adding a CEH to an async builder will have no effect.

Join the Discussion

  • Have you ever encountered a “silent failure” with async because you forgot to call await()?
  • Do you prefer the safety of supervisorScope for all concurrent work, or do you stick to standard scopes for stricter consistency?
  • How are you currently tracking logs across a massive coroutine-based architecture?

📘 Master Your Next Technical Interview

Since Java is the foundation of Android development, mastering DSA is essential. I highly recommend “Mastering Data Structures & Algorithms in Java”. It’s a focused roadmap covering 100+ coding challenges to help you ace your technical rounds.

Comments

Post a Comment

Popular posts from this blog

Stop Writing Massive when Statements: Master the State Pattern in Kotlin

Image
 Tame Your Codebase with Elegant, Scalable, and Type-Safe State Machines Do you manage complex objects that change their behavior dramatically based on their internal status? If so, you’ve likely battled a common foe: the sprawling  when  statement that haunts every method in your class. It looks something like this: fun handleAction () { when (state) { State.A -> { /* logic for A */ } State.B -> { /* logic for B */ } State.C -> { /* logic for C */ } // ... and the list keeps growing! } } Every time you add a new state (e.g.,  State.D ), you have to hunt down and update  every single function  with a new case. This is a maintenance nightmare, a direct violation of the  Open/Closed Principle  (OCP), and a major code smell. Your logic is scattered by  action  when it should be grouped by  state . The solution? The  State Pattern . And with modern Kotlin, we can implement it w...
Read more

Coroutines & Flows: 5 Critical Anti-Patterns That Are Secretly Slowing Down Your Android App

Image
 Stop sneaky performance killers. Spot and fix Kotlin issues that cause crashes, memory leaks, and laggy UIs. Coroutines and Kotlin Flows are the bedrock of modern asynchronous programming on Android. They allow us to write clean, sequential-looking code that manages complex background operations, network calls, and database transactions. But power comes with responsibility. Many developers, despite using Coroutines daily, unknowingly introduce subtle mistakes —  anti-patterns  — that lead to memory leaks, silent crashes, data loss, and UI jank. Based on insights from top-tier Android development, here are five critical Coroutine and Flow anti-patterns you must identify and fix today, plus one bonus pitfall I often see in code reviews. 1. The Main Thread Trap: Heavy Work in  viewModelScope When you launch a coroutine inside a  ViewModel  using  viewModelScope.launch { ... } , where do you think that work runs by default? The  Main Thread ! If your...
Read more

Master Time with Kotlin's Stable Timing API: Beyond System.nanoTime()

Image
 Learn how to use type-safe Durations, measure execution time, and simplify unit testing with Kotlin 1.6+. Managing time in software is a ubiquitous challenge. From measuring performance to scheduling events, accurate and robust timing is crucial. For years, many Kotlin developers relied on manual  Long  calculations with  System.nanoTime() . While functional, this approach was prone to unit confusion and lacked type safety. Enter the  stable  kotlin.time  API  (fully stable since Kotlin 1.6). This powerful toolset provides a type-safe, idiomatic, and highly readable way to handle durations. It eliminates the guesswork and boilerplate, allowing you to write cleaner, more maintainable code. Quick Tip:  To follow along with the examples below, you’ll want to include this import at the top of your file:  import kotlin.time.* Why Ditch Manual Long Calculations? Imagine you’re tracking the execution time of a critical network request using th...
Read more