CompletableFuture Exception Handling — exceptionally vs handle vs whenComplete

CompletableFuture has three exception-handling hooks with distinct semantics.

`exceptionally(fn)` — recover on failure

• Function
• Runs only on upstream failure; success value passes through untouched
• Returns a replacement value; the resulting future succeeds
• Same type T in and out
• Use for: "on error, fall back to cached/default value"
• Java 12+ adds exceptionallyAsync (on executor) and exceptionallyCompose (async fallback)

`handle(biFn)` — transform both branches

• BiFunction
• Runs on both success and failure; one of the two params is null
• Can change type: T → U
• Returns new value; exception is swallowed unless biFn rethrows
• Use for: uniform response builder (wrap result or error into a Response object), metric recording with typed return

`whenComplete(biCons)` — observe, don't touch

• BiConsumer
• Runs on both branches
• Cannot change the result — pass-through
• Exception propagates downstream unchanged
• Use for: logging, metrics, audit trails
• If biCons itself throws, the new exception suppresses the original

Decision guide

• Need fallback value on error? → exceptionally
• Need to transform both branches into a unified result? → handle
• Need side effects without altering outcome? → whenComplete

The silent-failure trap

• A chain with no terminator loses exceptions
• future.thenCompose(x).thenApply(y); — returns void, exception vanishes
• Fix: always end with whenComplete + exceptionally, or return the future to someone who .join()s

CompletionException wrapping

• Inside exception hooks, the Throwable is typically wrapped
• ex.getCause() to get the real exception
• At .join(): throws CompletionException (unchecked); unwrap with getCause
• At .get(): throws ExecutionException (checked); same getCause dance

Common patterns

• Tap-then-recover: .whenComplete(log) then .exceptionally(fallback) — log every outcome, fall back on errors
• Typed filter: inside exceptionally, check ex.getCause() type; rethrow others as CompletionException
• Retry: extract a helper that composes handle + re-invocation of the async supplier

Recommendation: Treat every CompletableFuture chain like a promise chain in JavaScript — terminate it with a handler, or pass it to a caller who will. An unterminated chain that fails is indistinguishable from a successful one and creates the nastiest kind of silent bug. Use `exceptionally` for simple fallback, `handle` when you want to unify success and failure into one response type, `whenComplete` as a logging tap that doesn't change semantics. And always write a helper that unwraps `CompletionException` before matching on exception types — that code gets written once, used everywhere, and saves hours of debugging.