Skip to content
AppDues
Log in
Contact salesSign up

SupervisorJob in Kotlin Coroutines: Failure Isolation Explained

Kotlin coroutines give you structured concurrency by default: a failing child cancels its parent, and the parent cancels its siblings. That is the right default for many tasks, but not all. This guide explains how SupervisorJob changes that propagation rule, how supervisorScope creates a temporary supervisory scope, and how to handle the exception that no longer travels upward.

Job vs SupervisorJob: the core difference

A plain Job follows a strict all-for-one policy. When a child coroutine launched in a scope fails with a non-cancellation exception, the failure reaches the parent Job, and the parent cancels its other children. That behavior is predictable and often correct, but it is not what you want when independent tasks should survive each other's failures.

SupervisorJob changes the rule at the parent. A child can fail without cancelling the supervisor or its siblings. The failure is contained to that child, which is the fault-isolation pattern you want for independent work such as separate network requests or independent UI data streams.

The two code modules below show the contrast directly. In the first, a failure in Child 2 cancels the parent and therefore Child 1 and Child 3. In the second, the same failure is isolated and the other children keep running.

How SupervisorJob works internally

The public SupervisorJob(parent) function is a small factory. It returns a SupervisorJobImpl, which extends JobImpl. The only behavioral change is an override of childCancelled(cause).

In a standard Job, childCancelled treats a CancellationException as normal and returns true. For any other exception it calls cancelImpl(cause), which cancels the parent. That is the mechanism that propagates failure upward.

SupervisorJobImpl overrides childCancelled to always return false. The supervisor is effectively saying that it has received the child's failure notification but will not cancel itself. The child's failure stays contained, the supervisor remains active, and the other children continue. The exception is not swallowed silently: responsibility moves to a CoroutineExceptionHandler in the child's context, or to the consumer of an async Deferred result.

The supervisorScope builder

supervisorScope creates a temporary supervisory scope for a block of suspending code. Internally it creates a SupervisorCoroutine, which acts as the root of that scope and overrides childCancelled to return false, just like SupervisorJobImpl.

Any coroutine launched inside the block has the SupervisorCoroutine as its parent. A failure in one of those children stops at that root and does not leak out to cancel the outer scope that called supervisorScope. Use it when you need isolation for a bounded section of work rather than for the lifetime of a long-lived scope.

Where SupervisorJob is used in practice

Two common examples show the pattern in production code.

In the Android SDK for in-app subscriptions, a BlockstoreHelper interacts with Google's Block Store API to back up and restore an anonymous user ID. An exception during a Block Store operation must not crash the host app, so the helper defines dedicated CoroutineScopes configured with SupervisorJob. Failures in one suspend call do not propagate to other requests in the same scope.

In Android ViewModel, viewModelScope is built with a SupervisorJob. A profile screen might fetch the user's profile, observe incoming messages, and listen for online-status updates as three independent launches. If the message stream fails, only that launch fails; profile fetching and status observation continue. Without the supervisor, one network error in chat could cancel the whole ViewModel scope and leave the UI inconsistent.

Decision checklist: Job, SupervisorJob, or supervisorScope?

Use this checklist before choosing a parent job type:

  • Use a plain Job when the tasks are a single unit of work and one failure should stop the rest. This is the default and usually the safest choice.
  • Use SupervisorJob when independent tasks share a long-lived scope and each should survive the others' failures, as in the BlockstoreHelper and viewModelScope examples.
  • Use supervisorScope when you need isolation only for a bounded block of suspending code, not for the lifetime of a scope.
  • Always attach a CoroutineExceptionHandler or consume the Deferred result when using a supervisor, because the isolated failure still needs to be handled somewhere.
  • Remember that CancellationException is treated as normal and does not cancel the parent in either case.

Clarifying the failure distinction

SupervisorJob does not make exceptions disappear. It changes who gets cancelled. In a standard Job, a non-cancellation child exception cancels the parent and siblings. In a supervisor, the child fails, the parent stays active, and siblings keep running. The exception still needs a destination: a CoroutineExceptionHandler in the child's context, or the consumer awaiting an async Deferred.

A CancellationException is different. It is considered normal cancellation and does not cancel the parent even in a standard Job. If you are debugging why a supervisor did not stop a sibling, check whether the failure was actually a cancellation rather than an unhandled exception.

Frequently asked questions

When should I use SupervisorJob instead of a regular Job?

Use SupervisorJob when independent child coroutines share a scope and one child's failure should not cancel the others. If the children form a single unit of work where any failure should stop the rest, the default Job is the safer choice.

If SupervisorJob isolates a failure, who handles the exception?

The exception is not handled by the supervisor. It is delegated to a CoroutineExceptionHandler in the child's context, or to the consumer of an async Deferred result. Without one of those, the failure may go unobserved.

What is the difference between supervisorScope and SupervisorJob?

supervisorScope creates a temporary supervisory scope for a block of suspending code, using an internal SupervisorCoroutine as the root. SupervisorJob is a Job type you can install in a long-lived CoroutineScope. Both stop child failures from propagating upward, but they apply over different lifetimes.

Does a CancellationException cancel the parent in a regular Job?

No. In a standard Job, childCancelled returns true for a CancellationException, treating it as normal cancellation. Only non-cancellation exceptions trigger cancelImpl(cause) and cancel the parent.