A CompletableFuture exception swallowed silently

What this error actually means

A `CompletableFuture` that fails does not throw anywhere. The exception is *captured* as the completion value of that future and then propagated down the dependent chain as a result, not as a control-flow event. If nobody ever asks the last future in the chain what happened — no `join`, no `get`, no `exceptionally`, no `whenComplete` — the exception is stored in an object that becomes garbage, and the failure leaves no trace at all.

This is a deliberate design choice and it is the opposite of how a thread-based task behaves. An exception escaping a `Runnable` on a raw thread reaches the thread’s uncaught-exception handler and gets printed. An exception inside a `CompletableFuture` stage never escapes: the framework catches it precisely so it can be delivered to whoever asks. There is no default handler in the path because, from the framework’s point of view, nothing went uncaught.

The gap widens with `thenApply` chains whose returned future is discarded. Calling `future.thenApply(this::render)` and ignoring the result creates a new future that will hold the failure of either stage and be immediately unreferenced. The work still runs, the error still occurs, and the return value you dropped was the only handle to the outcome.

Two further details make the trace harder to read when you do finally see it. Exceptions are wrapped — `CompletionException` from `join`, `ExecutionException` from `get` — so the type you catch is not the type that was thrown, and naive `catch (IllegalStateException e)` around a `join` does not match. And the stack trace contains the async stage frames but not the frames of the code that *started* the pipeline, because that code is no longer on any stack.

How to diagnose it

future.whenComplete((v, ex) -> {
    if (ex != null) log.error("stage failed", ex);
});

./gradlew compileJava -PerrorProneChecks=FutureReturnValueIgnored

Throwable root = (ex instanceof CompletionException || ex instanceof ExecutionException)
    ? ex.getCause() : ex;

jcmd <pid> Thread.print | grep -c "ForkJoinPool.commonPool-worker"

The fix

Terminate every chain with a handler, and make that a rule rather than a habit. A final `whenComplete` that logs the throwable and increments a failure counter costs one line and converts an invisible failure class into an observable one. `whenComplete` is the right choice for the terminal position because it observes both outcomes and, unlike `handle`, does not require you to invent a substitute value.

Never discard the future returned by a `then*` method. Either return it to the caller so the failure becomes their problem to handle, or attach the terminal handler right there. An expression-statement call to `thenApply` is always a bug.

Choose between the three handlers on purpose. `exceptionally` recovers from a failure by supplying a fallback value and leaves success untouched — use it where a default is genuinely correct. `handle` sees both outcomes and must produce a value, so use it when the substitution depends on which happened. `whenComplete` observes both and changes neither, which is what you want for logging, metrics, and cleanup.

Always pass an explicit executor to `supplyAsync`, `thenApplyAsync`, and the rest. Defaulting to the common ForkJoinPool means your blocking work competes with parallel streams and library internals on a pool whose parallelism is one less than the processor count, and it is a direct route to the starvation failure where every worker waits on a stage that needs a worker.

Unwrap `CompletionException` and `ExecutionException` at the boundary before mapping errors to responses, and never catch the wrapper and log only its message. Carry the cause into whatever domain error your API returns, so the client-facing message and the logged trace describe the same failure.

For fan-out, inspect each leg individually rather than relying on `allOf`. Attach a handler per future so every failure is recorded, then use `allOf` purely as the barrier. Otherwise a fan-out where three of five legs fail is indistinguishable from one where one did.

For genuinely fire-and-forget work, decide explicitly whether losing it is acceptable. If it is not — an outbox write, an audit record — it does not belong in an unretained future at all; it belongs in a durable queue or a transactional outbox that survives process death as well as exceptions.

// Silent: the returned future holds the failure and is immediately garbage
CompletableFuture.supplyAsync(() -> loadOrder(id))
                 .thenApply(this::attachShipment);   // may throw; nobody asks

// Silent: exceptionally is not last, so render() failures are unobserved
future.exceptionally(ex -> Order.EMPTY)
      .thenApply(this::render);

// Observed: explicit executor, terminal handler, unwrapped cause
CompletableFuture<Shipment> f =
    CompletableFuture.supplyAsync(() -> loadOrder(id), ioPool)
                     .thenApplyAsync(this::attachShipment, cpuPool)
                     .whenComplete((v, ex) -> {
                         if (ex != null) {
                             log.error("shipment pipeline failed for order={}", id, unwrap(ex));
                             failures.increment();
                         }
                     });

static Throwable unwrap(Throwable t) {
    return (t instanceof CompletionException || t instanceof ExecutionException)
         ? t.getCause() : t;
}

// Fan-out: handle each leg, then use allOf only as the barrier
List<CompletableFuture<Leg>> legs = ids.stream()
    .map(i -> fetch(i, ioPool).whenComplete((v, ex) -> recordLeg(i, ex)))
    .toList();
CompletableFuture.allOf(legs.toArray(CompletableFuture[]::new))
                 .whenComplete((v, ex) -> finish(legs));

How to stop it coming back

• Enable Error Prone’s `FutureReturnValueIgnored` (or an equivalent SpotBugs rule) and treat it as an error, not a warning
• Require a terminal `whenComplete` on every chain in review; the absence of one is the bug, not a style choice
• Ban defaulted executors in async stages so pool ownership is always explicit and greppable
• Emit a metric from the terminal handler so async failures show up on dashboards rather than only in logs
• Unwrap completion exceptions in one shared helper, so no boundary logs the wrapper and loses the cause
• Move any async side effect you cannot afford to lose out of fire-and-forget futures and into a durable outbox

FAQ

Related

Other errors engineers hit next to this one

• Process exits before asynchronous writes finish
• ERR_MODULE_NOT_FOUND during ESM/CommonJS migration
• Unbounded JSON body blocks the loop or exhausts memory
• Undici / fetch connections remain occupied
• ERR_UNHANDLED_REJECTION in a worker thread
• command not found in a script that works interactively
• Permission denied when executing a script
• bad interpreter: No such file or directory with CRLF