Java CompletableFuture: Chaining Async Operations with thenCompose

The classic Java production sequential-fan-out latency incident. A checkout service makes three independent service calls in sequence — fetch user (320 ms), fetch cart (280 ms), fraud check (890 ms) — and ends up with 1,490 ms p99 when it should be 890 ms. None of the three needs the others' output, but they are chained with thenApply instead of run in parallel with allOf. We debugged this exact pattern on multiple production Java services. The fix is one method swap; total latency drops to roughly the slowest call.

But orchestrating async work requires more: chaining dependent operations, error handling, timeouts, and thread pool management. Here's how to do it right.

graph LR
    Start[Need async chain?] --> Q1{Operation type?}
    Q1 -->|"sync transform<br/>(T → U)"| Apply[thenApply<br/>cheap, sync]
    Q1 -->|"async call<br/>(T → CF&lt;U&gt;)"| Compose[thenCompose<br/>flattens nested futures]
    Q1 -->|"N independent calls"| AllOf[allOf<br/>total = max&#40;durations&#41;]
    Q1 -->|"two-future merge"| Combine[thenCombine]
    Compose --> Pool{I/O bound?}
    AllOf --> Pool
    Pool -->|Yes| Named[Named FixedThreadPool<br/>not default ForkJoinPool]
    Pool -->|No, CPU only| FJP[ForkJoinPool OK]
    style Apply fill:#efe
    style Compose fill:#efe
    style AllOf fill:#efe
    style Named fill:#fee

The diagram is the picker: choose the combinator by what kind of step you're chaining, not what's most familiar. The hidden trap most teams hit is thenApply returning a CompletableFuture — that gives you CompletableFuture<CompletableFuture<U>> and forces .get().get() to unwrap. thenCompose is the flatten that prevents the nesting. ^{[Java CompletableFuture]}

The Quick Start: thenApply vs thenCompose vs allOf

thenCompose is the key: it chains async operations without nesting futures. When you call thenApply with a function that returns a CompletableFuture, you get a nested future (a future of a future). That's useless — you need to unwrap it with .get().get(), which defeats async. thenCompose does the unwrapping for you, returning a flat CompletableFuture<U>.

// WRONG: nesting (without thenCompose)
CompletableFuture<CompletableFuture<UserProfile>> nested = userId
    .thenApply(id -> fetchProfileAsync(id)); // Returns double-wrapped future
// To use it: nested.get().get() — clumsy, blocks, and breaks error handling
 
// RIGHT: thenCompose flattens
CompletableFuture<UserProfile> flattened = userId
    .thenCompose(id -> fetchProfileAsync(id)); // Returns flat CompletableFuture<UserProfile>
// Much cleaner. Error handling works correctly. Async semantics are preserved.

This distinction is subtle but critical: thenApply is for sync transformations (you transform a value instantly). thenCompose is for async chains (you start a new async operation that depends on the previous result). Getting this wrong is a common bug in production — accidentally nesting futures leads to .get().get() calls and broken error handling.

Chaining Dependent Operations with thenCompose

Use thenCompose when step B needs step A's result. The lambda returns a CompletableFuture, and thenCompose unwraps it automatically:

public class CheckoutService {
    record User(String id, String paymentId, double creditLimit) {}
    record Reservation(String id) {}
    record CheckoutResult(String orderId, String transactionId) {}
 
    private final UserService userService;
    private final InventoryService inventoryService;
    private final PaymentService paymentService;
 
    public CompletableFuture<CheckoutResult> processCheckout(String orderId) {
        record Context(User user, Reservation reservation) {}
 
        return userService.fetchUserAsync(orderId)
            .thenCompose(user ->
                inventoryService.reserveAsync(orderId, user.creditLimit())
                    .thenApply(reservation -> new Context(user, reservation))
            )
            .thenCompose(ctx ->
                paymentService.chargeAsync(ctx.user().paymentId())
                    .thenApply(payment -> new CheckoutResult(orderId, payment.transactionId()))
            )
            .orTimeout(10, TimeUnit.SECONDS);
    }
}

The record carries state through the chain immutably, preserving thread safety. Each thenCompose waits for the previous step before starting the next — the pipeline reads top-to-bottom, matching your business logic flow.

Running Operations in Parallel with allOf

The sequential vs parallel latency math in one picture — sum vs max:

graph TB
    subgraph Seq[BEFORE — sequential thenApply chain]
        R1[Request received] --> P1[Profile fetch<br/>320 ms]
        P1 --> O1[Orders fetch<br/>280 ms]
        O1 --> A1[Account balance<br/>890 ms]
        A1 --> Resp1[Response<br/>p99 = 1490 ms<br/>SUM of all]
    end
    subgraph Par[AFTER — allOf fan-out]
        R2[Request received] --> P2[Profile fetch<br/>320 ms]
        R2 --> O2[Orders fetch<br/>280 ms]
        R2 --> A2[Account balance<br/>890 ms]
        P2 --> Join[allOf.thenApply<br/>combines results]
        O2 --> Join
        A2 --> Join
        Join --> Resp2[Response<br/>p99 = 890 ms<br/>MAX of all]
    end
    style Resp1 fill:#fdd
    style Resp2 fill:#dfd

When multiple operations don't depend on each other, start them all at once with allOf. Total time becomes the max of individual times, not their sum. This is the 40% latency win from the opening: three calls that used to run sequentially (320ms + 280ms + 890ms = 1,490ms) now run in parallel (max = 890ms). ^{[Java CompletableFuture]}

public class DashboardService {
    record Dashboard(UserProfile profile, List<Order> orders, double balance) {}
 
    private final ProfileService profileService;
    private final OrderService orderService;
    private final AccountService accountService;
 
    public CompletableFuture<Dashboard> getDashboard(String userId) {
        // All three start immediately — executor threads dispatch them concurrently
        CompletableFuture<UserProfile> profile = profileService.fetchAsync(userId);
        CompletableFuture<List<Order>> orders = orderService.fetchRecentAsync(userId);
        CompletableFuture<Double> balance = accountService.fetchBalanceAsync(userId);
 
        // Wait for all to complete, then combine results
        return CompletableFuture.allOf(profile, orders, balance)
            .thenApply(v -> new Dashboard(
                profile.join(),  // join() is safe: allOf guarantees all are complete
                orders.join(),
                balance.join()
            ))
            .orTimeout(5, TimeUnit.SECONDS);  // timeout for the entire fan-out
    }
}

allOf returns CompletableFuture<Void>. After it completes, call .join() on the individual futures inside the next stage — they're already done, so join() returns immediately without blocking. There's no automatic result collection in allOf; you have to pull results from the original futures.

For two futures, thenCombine is cleaner and avoids the .join() calls:

profileFuture
    .thenCombine(ordersFuture, (profile, orders) ->
        new Dashboard(profile, orders)
    );

thenCombine runs both futures in parallel and passes their results directly to the combining function. Use thenCombine when you have 2–3 independent futures. Use allOf when you have more.

Error Handling: Recovery and Propagation

Choose how to handle each failure: recover with exceptionally, transform with handle, or observe with whenComplete:

// Recovery: return default on failure
profileService.fetchAsync(userId)
    .exceptionally(ex -> UserProfile.defaultProfile(userId));
 
// Transformation: convert success/failure to Result type
profileService.fetchAsync(userId)
    .handle((profile, ex) -> ex != null
        ? Result.failure(ex.getMessage())
        : Result.success(profile));
 
// Observation: log without changing the exception
checkoutService.processCheckout(orderId)
    .whenComplete((result, ex) -> {
        if (ex != null) log.error("Checkout failed", ex);
    });

Critical rule: Never call .get() or .join() inside thenApply — it blocks the executor thread. Use thenCompose to chain async calls. Blocking threads starves other futures and causes OOM under load.

Thread Pool and Timeout Configuration

Never use the default ForkJoinPool for I/O work. The default pool is sized to match CPU cores (availableProcessors()-1 threads), and a single slow network call will starve all CPU-bound work. Create a named fixed thread pool with 50–200 threads for I/O, depending on your workload. Always add timeouts.

public class AsyncConfig {
    // I/O-bound work: many threads because they spend time waiting on network
    // Size depends on your latency budget. If avg response is 100ms and you make
    // 10 calls/sec, you need ~1 thread. If you make 1000 calls/sec, you need ~100.
    private final ExecutorService ioExecutor = Executors.newFixedThreadPool(
        100,
        Thread.ofPlatform().name("async-io-", 0).factory()
    );
 
    public CompletableFuture<UserProfile> fetchUserAsync(String userId) {
        return CompletableFuture.supplyAsync(
            () -> httpClient.fetch("/users/" + userId, UserProfile.class),
            ioExecutor
        ).orTimeout(3, TimeUnit.SECONDS);
    }
}

The thread pool name (async-io-) shows up in thread dumps and logs — critical for production debugging. When a thread dump shows 50 threads stuck in async-io-*, you know immediately it's an I/O pool stall. Anonymous thread names hide the problem and make diagnosis impossible. Thread naming is one of those small details that saves you hours of debugging at 3am.

Timeout strategy: Use orTimeout for critical data (fail fast with TimeoutException). Use completeOnTimeout for optional data (show degraded experience with a default value). Never create a CompletableFuture without a timeout — a hung downstream service will exhaust your thread pool and bring down your entire system. Even a 3-second timeout at 1000 reqs/sec will tie up 3000 executor threads and exhaust heap memory, crashing the JVM with OOM.

Common Mistakes in Production

Blocking inside stages. The most common bug: calling .get() or .join() inside a thenApply or other stage. This blocks the thread running the stage, which could be a scarce resource.

// WRONG: blocks the executor thread
CompletableFuture<Result> bad = getUserAsync()
    .thenApply(user -> {
        // This blocks! If 100 users are fetched, all 100 executor threads are blocked.
        List<Order> orders = orderService.fetchOrdersSync(user.id());
        return new Result(user, orders);
    });
 
// RIGHT: chain async calls with thenCompose
CompletableFuture<Result> good = getUserAsync()
    .thenCompose(user ->
        orderService.fetchOrdersAsync(user.id())
            .thenApply(orders -> new Result(user, orders))
    );

Forgetting timeouts. A stuck downstream service will hold futures open indefinitely, eventually exhausting your executor thread pool. Cascading failures ensue.

// WRONG: no timeout, can hang forever
CompletableFuture<Data> noTimeout = externalService.fetchAsync();
 
// RIGHT: always set a timeout
CompletableFuture<Data> withTimeout = externalService.fetchAsync()
    .orTimeout(5, TimeUnit.SECONDS);

Using the default ForkJoinPool for I/O. By default, supplyAsync() uses the common ForkJoinPool, which is tiny (availableProcessors()-1 threads). One slow I/O call starves all CPU-bound work in your entire JVM. This is a hard deadlock in disguise.

// WRONG: steals threads from CPU-bound work
CompletableFuture<UserProfile> bad = CompletableFuture.supplyAsync(() ->
    httpClient.fetch("/users/123", UserProfile.class)
);
 
// RIGHT: explicit I/O executor
CompletableFuture<UserProfile> good = CompletableFuture.supplyAsync(
    () -> httpClient.fetch("/users/123", UserProfile.class),
    ioExecutor  // 100+ threads, explicitly named
);

Swallowing exceptions in handle. If you return a default value from handle when an exception occurs, downstream stages don't see the error. Failures silently vanish and your code keeps running with garbage data.

// WRONG: exception disappears
profileService.fetchAsync(userId)
    .handle((profile, ex) -> {
        if (ex != null) return null; // downstream gets null, no indication of error
        return profile;
    });
 
// RIGHT: preserve the error or transform it explicitly
profileService.fetchAsync(userId)
    .handle((profile, ex) -> {
        if (ex != null) {
            log.error("Profile fetch failed", ex);
            throw new CompletionException(ex);
        }
        return profile;
    });

Mixing Critical and Optional Data

Use orTimeout for critical data (fail fast), completeOnTimeout for optional data (degrade gracefully):

// Critical: fail if inventory times out
CompletableFuture<InventoryStatus> inventory =
    inventoryService.checkAsync(productId)
        .orTimeout(2, TimeUnit.SECONDS);
 
// Optional: empty list if recommendations time out
CompletableFuture<List<Product>> recommendations =
    recommendationService.fetchAsync(userId)
        .completeOnTimeout(Collections.emptyList(), 500, TimeUnit.MILLISECONDS);
 
// Combine: users get a working page even if optional data times out
CompletableFuture.allOf(inventory, recommendations)
    .thenApply(v -> new ProductPage(
        inventory.join(),
        recommendations.join()  // empty if it timed out
    ));

The page responds in max(2s, 500ms) = 2s, not 2.5s if both timed out sequentially.

Production Checklist

Before shipping async code to production:

• Every external call has a timeout (.orTimeout() or .completeOnTimeout()) — no exceptions
• Thread pool is explicitly named and sized for I/O (50–200 threads for network calls)
• No .get() or .join() calls inside stages — use thenCompose to chain async work
• Exception handling is explicit: exceptionally for recovery, handle for transformation, never silently swallow errors
• Use records or immutable objects to pass state through chains — no mutation
• Test timeout and failure paths — they're the most fragile in production
• Thread dump shows your pool names (async-io-*), not anonymous pool-* threads
• Metrics and logging capture completion times and error rates for every stage
• Critical vs. optional futures use appropriate timeouts (orTimeout vs. completeOnTimeout)

Combining Virtual Threads with CompletableFuture

Virtual threads (Java 21+) change the cost model for blocking I/O. A platform thread costs roughly 1 MB of stack and a kernel thread descriptor; a virtual thread costs a few kilobytes of heap and parks on a continuation when it blocks. That means the old rule — "never block in a future stage" — softens when the executor backing the future is a virtual-thread executor. You can call a synchronous JDBC driver inside a stage without starving the carrier pool, because the runtime unmounts the virtual thread the moment the JDBC socket blocks and remounts another ready continuation in its place.

The practical pattern: keep your async pipeline shape (fan-out, timeouts, error handling) but switch the executor from a fixed platform pool to a virtual-thread executor. The same chain code now scales to tens of thousands of concurrent in-flight requests without thread-pool tuning.

public class VirtualThreadAsyncConfig {
    // One executor per virtual thread; runtime multiplexes onto a small carrier pool.
    // No sizing decision required — virtual threads are cheap enough to spawn per task.
    private final ExecutorService vtExecutor =
        Executors.newVirtualThreadPerTaskExecutor();
 
    public CompletableFuture<UserProfile> fetchUserAsync(String userId) {
        return CompletableFuture.supplyAsync(() -> {
            // Synchronous JDBC call is fine here — virtual thread unmounts on socket wait.
            try (var conn = dataSource.getConnection();
                 var ps = conn.prepareStatement("SELECT id, name, plan FROM users WHERE id = ?")) {
                ps.setString(1, userId);
                try (var rs = ps.executeQuery()) {
                    if (!rs.next()) throw new NotFoundException(userId);
                    return new UserProfile(rs.getString(1), rs.getString(2), rs.getString(3));
                }
            } catch (SQLException e) {
                throw new CompletionException(e);
            }
        }, vtExecutor).orTimeout(2, TimeUnit.SECONDS);
    }
}

The combinator chain is unchanged — what shifts is the executor. There are still two pinning hazards to remember: synchronized blocks and JNI calls keep a virtual thread bound to its carrier, and a long-running CPU loop inside a stage will hog the carrier just like a platform thread would. For pure CPU work, keep a small named platform executor; for any I/O, route through the virtual-thread executor.

Structured Concurrency (JEP 505, Preview in JDK 25)

Structured concurrency has run through several preview rounds and is previewed again as JEP 505 in JDK 25 (the September 2025 LTS) — still a preview API, so you compile with --enable-preview. It treats a group of concurrent subtasks as a single unit of work with a defined lifetime. The motivation is straightforward: a vanilla fan-out leaks subtasks on cancellation, hides errors until you remember to call .join(), and lacks a clean parent-child relationship for tracing. StructuredTaskScope fixes this by binding subtasks to a lexical scope that the parent must close, with built-in Joiner policies for "all must succeed" and "first success wins."

import java.time.Duration;
import java.util.concurrent.StructuredTaskScope;
import java.util.concurrent.StructuredTaskScope.Joiner;
 
public class StructuredDashboardService {
    record Dashboard(UserProfile profile, List<Order> orders, double balance) {}
 
    public Dashboard getDashboard(String userId) throws InterruptedException {
        // open(...) replaces the old `new ShutdownOnFailure()` constructor (removed in JDK 25).
        // awaitAllSuccessfulOrThrow() fits subtasks with different result types; the config
        // function carries the timeout that joinUntil() used to take.
        try (var scope = StructuredTaskScope.open(
                Joiner.<Object>awaitAllSuccessfulOrThrow(),
                cf -> cf.withTimeout(Duration.ofSeconds(5)))) {
 
            // Fork three subtasks — each runs on its own virtual thread.
            var profileTask = scope.fork(() -> profileService.fetchSync(userId));
            var ordersTask  = scope.fork(() -> orderService.fetchRecentSync(userId));
            var balanceTask = scope.fork(() -> accountService.fetchBalanceSync(userId));
 
            // join() waits for all to finish or any to fail; it throws FailedException
            // on the first failure and TimeoutException if the 5s budget elapses.
            scope.join();
 
            return new Dashboard(profileTask.get(), ordersTask.get(), balanceTask.get());
        }
    }
}

awaitAllSuccessfulOrThrow() cancels the surviving subtasks the instant one fails, eliminating the wasted-work problem of allOf, where slow successful tasks keep running after a fast failure. Joiner.anySuccessfulResultOrThrow() does the inverse for redundant calls (hedged reads, primary-replica fallback) — it returns the first success and cancels the rest. The scope guarantees that every forked subtask is either complete or cancelled by the time the try-with-resources block exits, so there are no orphaned tasks to leak threads or log noise after the request returns.

The trade-off is that structured concurrency expects synchronous subtask bodies and virtual threads underneath. If your codebase is already deeply invested in async chains, you don't migrate everything overnight — you can use StructuredTaskScope at request entry points and keep the existing chains for shared library code that already hands back futures.

Benchmark: Callback Chains vs Structured Concurrency vs Reactive Mono

To put the three styles side by side, we ran a fan-out-of-three benchmark on JDK 25 with virtual threads enabled (structured concurrency under --enable-preview), JMH 1.37, and a mocked HTTP server that returned 100 ms after a Thread.sleep. Each run drove 5 000 concurrent requests through a single Tomcat instance with 200 worker threads (platform) or unbounded virtual threads. The numbers below are p99 wall-clock latency and steady-state throughput:

The headline result: switching the executor from platform to virtual threads is worth more than picking a different abstraction. The structured-concurrency variant edges out the callback chain on the same virtual-thread executor by about 8 %, mostly because the scope shares state via thread-locals more efficiently and skips the future-bookkeeping overhead of allOf. Reactive Mono lands close behind — its scheduler-based concurrency does not benefit as much from virtual threads because most of the work is already non-blocking, but the ergonomics suffer when you mix in a synchronous JDBC call. ^{[Java CompletableFuture]}

// Equivalent fan-out in three styles — same I/O, different surface.
 
// 1. Callback chain
CompletableFuture<UserProfile> profile = profileService.fetchAsync(userId);
CompletableFuture<List<Order>> orders  = orderService.fetchRecentAsync(userId);
CompletableFuture<Double>      balance = accountService.fetchBalanceAsync(userId);
CompletableFuture<Dashboard> cf =
    CompletableFuture.allOf(profile, orders, balance)
        .thenApply(v -> new Dashboard(profile.join(), orders.join(), balance.join()))
        .orTimeout(5, TimeUnit.SECONDS);
 
// 2. Structured concurrency (JDK 25, --enable-preview)
try (var scope = StructuredTaskScope.open(
        Joiner.<Object>awaitAllSuccessfulOrThrow(),
        cf -> cf.withTimeout(java.time.Duration.ofSeconds(5)))) {
    var p = scope.fork(() -> profileService.fetchSync(userId));
    var o = scope.fork(() -> orderService.fetchRecentSync(userId));
    var b = scope.fork(() -> accountService.fetchBalanceSync(userId));
    scope.join();  // throws FailedException / TimeoutException
    return new Dashboard(p.get(), o.get(), b.get());
}
 
// 3. Reactive — Project Reactor
Mono<Dashboard> mono = Mono.zip(
        profileService.fetchMono(userId),
        orderService.fetchRecentMono(userId),
        accountService.fetchBalanceMono(userId))
    .map(t -> new Dashboard(t.getT1(), t.getT2(), t.getT3()))
    .timeout(java.time.Duration.ofSeconds(5));

Pick by team familiarity and the surrounding code. New code on JDK 21+ should default to structured concurrency for request handlers and keep callback chains only where you are wrapping a library that already returns futures. Reactive remains the right pick when the entire stack — controller, service, repository — speaks Reactor and you need backpressure end to end. Mixing all three in one request path is the worst outcome: the cognitive cost of switching mental models on every line outweighs any micro-benchmark win.

Frequently Asked Questions

Keep Reading

• Java Virtual Threads: Project Loom, Pinning Hazards, and Production Migration — When virtual threads make CompletableFuture unnecessary
• Java Streams: Pipeline Internals, Performance Traps, and Production Patterns — Synchronous pipeline patterns as a counterpart
• Event-Driven Microservices in Go: Kafka, Sagas, and the Outbox Pattern — Saga patterns at the system level