Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Java

CompletionException — wrapping a task failure

CompletionException is an unchecked exception signaling a failure while completing a task or result. With CompletableFuture, it carries the underlying failure to code retrieving the result through join().

Version: Java SE 21; repository runtime, production runtime not attested

Syntax

new CompletionException(Throwable cause)
new CompletionException(String message, Throwable cause)

CompletionException in java.util.concurrent extends RuntimeException, making it unchecked. It signals an exception or error encountered while completing a task or result. The underlying cause is available through the inherited getCause() method; it can be null.

The public constructors are CompletionException(Throwable cause) and CompletionException(String message, Throwable cause). The first derives its message as (cause == null ? null : cause.toString()). The no-argument constructor and the constructor taking only String have protected access.

For CompletableFuture, join() reports failure using CompletionException; get() uses the checked ExecutionException. Cancellation has a separate path: join() can throw CancellationException directly. Do not assume every failure has the same wrapper.

The example completes future exceptionally before calling join(). It displays the wrapper and its cause separately without starting additional threads. When diagnosing failures, preserve the cause rather than keeping only the wrapper's message.

Examples

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;

public class Main {
    public static void main(String[] args) {
        CompletableFuture<String> future = new CompletableFuture<>();
        future.completeExceptionally(new IllegalArgumentException("invalid input"));

        try {
            future.join();
        } catch (CompletionException ex) {
            Throwable cause = ex.getCause();
            System.out.println(ex.getClass().getSimpleName());
            System.out.println(cause.getClass().getSimpleName() + ": " + cause.getMessage());
        }
    }
}

Result

CompletionException
IllegalArgumentException: invalid input

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources