A CompletableFuture<CompletableFuture<T>> usually means a callback returned another future and the outer stage wrapped it instead of flattening it. Use thenApply when the callback returns a plain value; use thenCompose when it returns another stage. To control where the composition callback runs, use thenComposeAsync, optionally with an explicit executor.
Why does CompletableFuture become nested?
thenApply maps a completed value to a new value. If its function returns a CompletableFuture<Account>, the result is therefore a CompletableFuture<CompletableFuture<Account>>:
CompletableFuture<CompletableFuture<Account>> nested =
user.thenApply(this::loadAccount);The outer future represents completion of the callback that produces the inner future; it does not automatically replace itself with the inner future’s result.
When should you use thenApply or thenCompose?
| Method | Use it when | Result shape |
|---|---|---|
thenApply |
The function returns a plain value, such as converting a User to a display name. |
A future of the transformed value. |
thenCompose |
The function returns another CompletionStage, such as loading an account asynchronously for a user. |
A flattened future of the inner stage’s value. |
thenComposeAsync |
The function returns another stage and its invocation should be scheduled asynchronously. | A flattened future, with callback scheduling controlled by the default async facility or a supplied executor. |
For example, if loadAccount returns a future, compose the stages rather than wrapping one in another:
CompletableFuture<User> user = loadUser();
CompletableFuture<Account> account = user.thenCompose(this::loadAccount);thenCompose adopts the inner stage’s eventual value and exceptional completion, so the pipeline remains one stage. Oracle’s Java SE 26 API compares this operation to Optional.flatMap and Stream.flatMap: Oracle CompletableFuture API.
How do you choose where the composition runs?
Non-async dependent actions may run in the thread that completes the current stage. If the composition callback should be scheduled asynchronously, use thenComposeAsync. Its overload without an executor uses the default asynchronous facility; its executor overload lets you supply a scheduling policy:
Rank #2
CompletableFuture<Account> account =
user.thenComposeAsync(this::loadAccount, myExecutor);Choose an explicit executor when you need a controlled pool or want to isolate the callback from a thread that completes the preceding stage. The async and executor overloads are documented in the Java SE 26 CompletableFuture API.
Why is join throwing CompletionException?
join() is an intentional synchronous boundary: it waits for completion and reports exceptional completion through the unchecked CompletionException wrapper. get() also waits, but reports exceptional completion with ExecutionException; it may additionally throw InterruptedException or, when called with a timeout, TimeoutException. See Oracle’s CompletableFuture API.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsAvoid calling join() on the inner future inside a continuation just to make a nested result look flat. That can block the callback thread and makes the failure surface harder to follow. Return the inner stage from the callback and use thenCompose. At a genuine synchronous boundary, inspect the cause of CompletionException or ExecutionException deliberately. If using get(), handle interruption appropriately rather than silently discarding it.
How can you add a timeout without blocking?
Use a timeout stage operation rather than waiting in a callback. Choose the policy that matches the operation:
Rank #4
orTimeout(duration, unit)completes the future exceptionally withTimeoutExceptionif the deadline expires.completeOnTimeout(fallback, duration, unit)completes it with the supplied fallback value after the deadline.
These methods apply a timeout policy to the future; they do not require a blocking get(). Check the applicable JDK API documentation for their availability in the Java version you target: Oracle Java SE 26 CompletableFuture API.
How should you preserve failures and recovery?
exceptionally, handle, and whenComplete each return a stage. Keep that returned stage in the pipeline if later work depends on the recovered value or observed completion; invoking one and discarding its result does not change the reference you continue to use.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
Composition propagates exceptional completion from the inner stage, while terminal waiting methods expose wrapper exceptions. Keep asynchronous failures in the stage chain until a caller intentionally crosses a synchronous boundary, then handle the wrapper and its cause at that boundary.
Quick Recap
A practical decision checklist
- Does the callback return a plain value? Use
thenApply. - Does it return a future or other
CompletionStage? UsethenComposeto flatten the result. - Must the callback be scheduled asynchronously or on a particular pool? Use
thenComposeAsync, with an executor when needed. - Is waiting actually required at this point? If not, keep composing stages rather than calling
join()orget(). - Should a deadline fail the operation or return a fallback? Select
orTimeoutorcompleteOnTimeoutaccordingly.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
