Diagnosing Structured Concurrency Failures in Kotlin Coroutines

Recognizable condition

You notice that a coroutine launched from a parent scope continues to run after the parent has been cancelled, or you see unexpected code execution after a suspend point despite a CancellationException being thrown. These symptoms indicate a breakdown in structured concurrency guarantees.

Cause / Diagnostic table

Symptom	Likely cause	Quick diagnostic check
Child coroutine survives parent cancellation	Child launched with an explicit scope (GlobalScope or another CoroutineScope) instead of inheriting the parent’s job	Inspect the call site of launch/async: is the receiver this (the current scope) or an explicit scope?
CancellationException swallowed, code after suspend point runs	A catch block catches CancellationException and does not rethrow it	Search for catch (e: CancellationException) or a generic catch (e: Exception) lacking a rethrow or a guard if (e !is CancellationException)
Only the first child failure surfaces; others are lost	Using coroutineScope (fail‑fast) when independent error handling is needed	Count logged exceptions from children vs. the exception propagated to the parent; a mismatch indicates fail‑fast behavior
Resources (DB connections, file handles) leak after cancellation	Cleanup code placed after a suspend call without try/finally or use	Verify every acquire has a matching release in a finally block or via AutoCloseable.use()
Deadlock when parent waits on child that waits on parent	Circular wait via a shared mutex/semaphore or join() on a child that needs a resource held by the parent	Thread dump shows parent blocked in join()/await() while child is stuck on a lock owned by the parent
Job.isCancelled is true but coroutine makes no progress	Long‑running non‑suspending computation without periodic yield() or ensureActive() checks	Profile CPU: the coroutine thread stays at 100 % in the same stack frame for >1 s after cancellation
Parent failure does not cancel children when using SupervisorJob	Misunderstanding: SupervisorJob only shields the parent from child‑induced cancellation, not the reverse	Confirm the hierarchy: parent fails → children continue (expected); parent cancelled → children cancelled (expected)

Ordered checks

1. Verify scope inheritance
   • Where to run: IDE search or grep across the codebase.
   • Command example: grep -R "\.launch\|\.async" src/main/kotlin (requires read access to source).
   • Expected check: each call should have no explicit scope argument; the receiver is the current CoroutineScope.
   • Risk: false positives if you use extension receivers intentionally; verify context manually.
2. Look for unsafe cancellation handling
   • Where to run: same IDE search.
   • Command example: grep -R "catch.*CancellationException" src/main/kotlin.
   • Expected check: any matched block must either rethrow (throw e) or guard with if (e !is CancellationException).
   • Risk: missing a legitimate use‑case where you deliberately suppress cancellation; document why it is safe.
3. Confirm error‑propagation strategy
   • Where to run: runtime inspection.
   • Command example (JVM): add -Dkotlinx.coroutines.debug=on to the launch configuration and observe logs after a failure.
   • Expected check: stack traces show creation sites for each child; if only one trace appears, you are likely using coroutineScope.
   • Risk: debug flag adds overhead; disable in production builds.
4. Ensure resource cleanup follows suspend points
   • Where to run: code review.
   • Expected check: every acquisition (e.g., openDB(), File.open()) is paired with a release in a finally block or via use { … }.
   • Risk: missing a cleanup path in an early return; add unit tests that simulate cancellation.
5. Detect blocking loops
   • Where to run: profiler (Android Studio Profiler, Java Flight Recorder, or async-profiler).
   • Expected check: after cancelling a scope, the thread executing the coroutine shows a flat stack with no suspend points for >1 s.
   • Risk: profiler overhead may affect timing; use short‑lived test scenarios.
6. Validate supervisor semantics
   • Where to run: unit test with TestScope.
   • Expected check: parent cancellation cancels children; child failure does not cancel parent; parent failure leaves children alive.
   • Risk: test may pass due to timing; use advanceUntilIdle or advanceTimeBy to deterministic.

Fixes tied to findings

• Scope inheritance – Replace GlobalScope.launch { … } or someOtherScope.launch { … } with launch { … } (implicitly uses the current CoroutineScope) or pass the intended scope explicitly: viewModelScope.launch { … }.
• Unsafe cancellation handling – Change catch (e: CancellationException) { /* ignore */ } to catch (e: CancellationException) { throw e } or, if you need to perform cleanup, use finally instead of catch. For generic catches, add a guard:

  catch (e: Exception) {
      if (e !is CancellationException) {
          // handle other errors
      } else {
          throw e  // re‑throw cancellation
      }
  }

• Error propagation strategy – Switch from coroutineScope { … } to supervisorScope { … } when you need independent child failure handling. Keep coroutineScope for fail‑fast scenarios where any child error should cancel the whole operation.
• Resource cleanup – Wrap acquisition in use or try/finally:

  val connection = dataSource.getConnection()
  connection.use { /* work */ }
  // or
  try {
      val connection = dataSource.getConnection()
      // work
  } finally {
      connection.close()
  }

• Blocking loops – Insert a cancellation check inside long‑running loops:

  while (!isActive) { /* compute */ }
  // or
  for (item in items) {
      ensureActive()
      // process
  }

  If the work is CPU‑bound, move it to Dispatchers.Default.
• Supervisor semantics – No code change needed if the behavior matches expectations; otherwise, replace SupervisorJob() with a plain Job() when you want child failures to cancel the parent, or keep SupervisorJob and accept that parent failures still cancel children (as per the contract).

Escalation criteria

• If after applying the above checks the symptom persists for more than two hours of investigation, involve the team lead to review the concurrency architecture.
• When the issue appears in production and causes user‑visible stalls or resource leaks, create a high‑priority ticket and consider a hot‑fix that adds explicit ensureActive() or yield() calls.
• If the root cause lies in a third‑party library that improperly uses GlobalScope or swallows CancellationException, open an issue with the library maintainers and, as a temporary workaround, wrap the library call in a supervisor‑scoped coroutine that re‑throws cancellation.

Limitations and practical verification

This guide assumes you are using kotlinx.coroutines 1.6+ on the JVM or Android. It does not cover multi‑platform nuances (e.g., native memory‑management differences). To confirm that a fix works:

1. Run the problematic scenario with the parent scope cancelled.
2. Observe logs: child coroutines should log a CancellationException (or be absent if they completed cleanly).
3. Check resource usage (e.g., open file descriptors via lsof on Linux or Android Studio’s Profiler) to ensure no leaks.
4. If you added -Dkotlinx.coroutines.debug=on, verify that the stack traces now show the creation site of each child.

No state‑changing rollback is required for the diagnostic steps; code fixes should be committed via your usual version‑control workflow, and you can revert the change if the symptom reappears.