Java Exception Chaining

What Exception Chaining Is

Exception chaining means creating a new exception that keeps a reference to the exception that caused it. The original is called the cause. Each Throwable can hold one cause, and that cause can have its own cause, forming a chain:

OrderNotAvailableException: could not load order ORD-1001
   └── caused by SQLException: Connection refused: db-primary:5432

Chaining is used whenever code catches one exception and throws a different one. That happens constantly in layered applications: a low-level failure (a database error, an I/O error, a parsing error) is translated into an exception that makes sense at a higher level. Chaining lets you change the type and message of the exception without losing the original information — its type, message and stack trace — which is what you need to find the real problem.

The Problem: Losing the Original Exception

public class Lost {
    static int loadPort(String value) {
        try {
            return Integer.parseInt(value);
        } catch (NumberFormatException e) {
            throw new IllegalStateException("invalid server.port setting");
        }
    }

    public static void main(String[] args) {
        loadPort("80 80");
    }
}

Output:

Exception in thread "main" java.lang.IllegalStateException: invalid server.port setting
	at Lost.loadPort(Lost.java:6)
	at Lost.main(Lost.java:11)

The translation itself is reasonable: callers care that the configuration is invalid, not about parseInt. But the new exception was created without the original, so the log no longer shows what was wrong with the value. Was it empty? Too large? Containing letters? In a real system, someone now has to reproduce the problem to find out.

Chaining with a Constructor Argument

The fix is a single argument: pass the caught exception as the cause.

public class Kept {
    static int loadPort(String value) {
        try {
            return Integer.parseInt(value);
        } catch (NumberFormatException e) {
            throw new IllegalStateException("invalid server.port setting", e);
        }
    }

    public static void main(String[] args) {
        loadPort("80 80");
    }
}

Output:

Exception in thread "main" java.lang.IllegalStateException: invalid server.port setting
	at Kept.loadPort(Kept.java:6)
	at Kept.main(Kept.java:11)
Caused by: java.lang.NumberFormatException: For input string: "80 80"
	at java.base/java.lang.NumberFormatException.forInputString(NumberFormatException.java:67)
	at java.base/java.lang.Integer.parseInt(Integer.java:662)
	at java.base/java.lang.Integer.parseInt(Integer.java:778)
	at Kept.loadPort(Kept.java:4)
	... 1 more

Reading the chained trace:

• The top section is the exception that reached main: what went wrong at the application level and where it was thrown (line 6).
• Caused by: introduces the cause: what went wrong underneath — the value "80 80" contains a space — and its own stack trace, ending at line 4 of loadPort, where parseInt was called.
• ... 1 more means the remaining frame of the cause's stack trace is identical to the last frame of the exception above it (Kept.main), so Java omits the duplicate to keep the output short.

When debugging, the most useful line is usually the last Caused by: — the root cause — because it describes the original failure. The top-level exception explains its consequence.

The Chaining API

Every class that extends Throwable supports chaining through these constructors and methods:

RuntimeException, Error and Throwable have the same constructors. The behaviour of each:

public class Api {
    public static void main(String[] args) {
        Exception root = new java.io.FileNotFoundException("rates.json");
        RuntimeException a = new RuntimeException("cannot load rates", root);
        RuntimeException b = new RuntimeException(root);
        System.out.println("a.getMessage(): " + a.getMessage());
        System.out.println("a.getCause():   " + a.getCause());
        System.out.println("b.getMessage(): " + b.getMessage());
        System.out.println("root.getCause(): " + root.getCause());

        IllegalStateException legacy = new IllegalStateException("legacy wrapper");
        legacy.initCause(root);
        System.out.println("initCause: " + legacy.getCause());
        try {
            legacy.initCause(new RuntimeException("second"));
        } catch (IllegalStateException e) {
            System.out.println("second initCause: " + e.getMessage());
        }
    }
}

Output:

a.getMessage(): cannot load rates
a.getCause():   java.io.FileNotFoundException: rates.json
b.getMessage(): java.io.FileNotFoundException: rates.json
root.getCause(): null
initCause: java.io.FileNotFoundException: rates.json
second initCause: Can't overwrite cause with java.lang.RuntimeException: second

• a has its own message and keeps root as its cause.
• b was created with only a cause, so Java uses root.toString() as its message. That's convenient for pure wrapping, but a message describing what you were trying to do ("cannot load rates") is more informative.
• root has no cause, so getCause() returns null — the chain ends there.
• initCause exists for older exception classes that don't offer a (message, cause) constructor. It can be called only once, and only if no cause was passed to the constructor; otherwise it throws IllegalStateException. With modern exceptions, prefer the constructor.

Practical Example: Translating Exceptions Between Layers

A typical application has a data layer (talking to a database), a service layer (business logic) and a presentation layer (web controllers, UI). Each layer should throw exceptions that make sense at its own level of abstraction. The service layer shouldn't expose SQLException to its callers — they shouldn't need to know a SQL database exists — but the SQL details must remain available for whoever investigates the failure.

import java.sql.SQLException;
import java.util.*;

class OrderNotAvailableException extends RuntimeException {
    OrderNotAvailableException(String message, Throwable cause) {
        super(message, cause);
    }
}

class OrderRepository {
    String findStatus(String orderId) throws SQLException {
        // Simulates the JDBC driver failing to reach the database
        throw new SQLException("Connection refused: db-primary:5432", "08001");
    }
}

class OrderService {
    private final OrderRepository repo = new OrderRepository();

    String trackingStatus(String orderId) {
        try {
            return repo.findStatus(orderId);
        } catch (SQLException e) {
            throw new OrderNotAvailableException("could not load order " + orderId, e);
        }
    }
}

public class Layers {
    static Throwable rootCause(Throwable t) {
        Throwable current = t;
        while (current.getCause() != null && current.getCause() != current) {
            current = current.getCause();
        }
        return current;
    }

    public static void main(String[] args) {
        OrderService service = new OrderService();
        try {
            service.trackingStatus("ORD-1001");
        } catch (OrderNotAvailableException e) {
            System.out.println("User sees: Order status is temporarily unavailable.");
            System.out.println("Log: " + e.getMessage());
            Throwable root = rootCause(e);
            if (root instanceof SQLException sql) {
                System.out.println("Root cause: " + sql.getMessage() + " (SQLState " + sql.getSQLState() + ")");
            }
            System.out.println("--- full stack trace ---");
            e.printStackTrace(System.out);
        }
    }
}

Compile and run:

javac Layers.java
java Layers

Output:

User sees: Order status is temporarily unavailable.
Log: could not load order ORD-1001
Root cause: Connection refused: db-primary:5432 (SQLState 08001)
--- full stack trace ---
OrderNotAvailableException: could not load order ORD-1001
	at OrderService.trackingStatus(Layers.java:24)
	at Layers.main(Layers.java:41)
Caused by: java.sql.SQLException: Connection refused: db-primary:5432
	at OrderRepository.findStatus(Layers.java:13)
	at OrderService.trackingStatus(Layers.java:22)
	... 1 more

Step by step:

1. Data layer. OrderRepository.findStatus declares throws SQLException, as JDBC code does. The simulated failure uses the (reason, SQLState) constructor; 08001 is the standard SQLState for "unable to establish a connection".
2. Translation in the service layer. OrderService catches the checked SQLException and throws an unchecked, domain-level OrderNotAvailableException, passing e as the cause. Its signature has no throws SQLException, so the controller layer is independent of the database technology. Switching to a NoSQL store later wouldn't change any caller.
3. The custom exception supports chaining by offering a (message, cause) constructor that calls super(message, cause). Without it, the cause couldn't be passed in.
4. Presentation layer. main (standing in for a controller) shows a friendly message to the user and logs the technical details. Users should never see SQL errors or host names — that would be both confusing and a security risk — but operators need them.
5. Walking the chain. rootCause follows getCause() until it reaches an exception without a cause. The current.getCause() != current check guards against a self-referencing cause, which some older libraries produce. The instanceof SQLException sql pattern then gives typed access to getSQLState(), so the handler could, for example, retry on connection errors but not on syntax errors.
6. The full trace printed with printStackTrace(System.out) shows both levels. The top part says what the application was doing; Caused by: says why it failed. A logging framework call such as log.error("could not load order", e) prints the same chain.

Frameworks apply exactly this pattern. Spring, for instance, translates SQLExceptions into its unchecked DataAccessException hierarchy (such as DataAccessResourceFailureException) while keeping the original as the cause.

Wrapping Checked Exceptions in Unchecked Ones

Chaining is also how checked exceptions are carried through code that can't declare them, such as lambdas used with forEach or streams:

import java.io.*;
import java.nio.file.*;
import java.util.*;

public class Wrapper {
    public static void main(String[] args) {
        List<Path> files = List.of(Path.of("does-not-exist.txt"));
        try {
            files.forEach(p -> {
                try {
                    System.out.println(Files.readString(p));
                } catch (IOException e) {
                    throw new UncheckedIOException("reading " + p, e);
                }
            });
        } catch (UncheckedIOException e) {
            System.out.println(e.getMessage() + " -> " + e.getCause());
        }
    }
}

Output:

reading does-not-exist.txt -> java.nio.file.NoSuchFileException: does-not-exist.txt

UncheckedIOException requires a cause in every constructor — it exists only to carry an IOException — and its getCause() is declared to return IOException, so you can rethrow or inspect the original without a cast. After the lambda, the caller can unwrap and handle the real failure. Never wrap without a cause: throw new RuntimeException("read failed") in that catch would discard the file name and the reason.

Exceptions Wrapped by the JDK

Some JDK APIs perform chaining for you, and you must unwrap the cause to see what really happened. The most common is ExecutionException, thrown by Future.get() when a task running in another thread fails:

import java.util.List;
import java.util.concurrent.*;

public class Futures {
    static double fetchPrice(String sku) {
        if (sku.isBlank()) throw new IllegalArgumentException("sku must not be blank");
        return 120.0;
    }

    public static void main(String[] args) throws InterruptedException {
        try (ExecutorService pool = Executors.newFixedThreadPool(2)) {
            Future<Double> ok = pool.submit(() -> fetchPrice("PEN-01"));
            Future<Double> bad = pool.submit(() -> fetchPrice(" "));
            for (Future<Double> f : List.of(ok, bad)) {
                try {
                    System.out.println("price = " + f.get());
                } catch (ExecutionException e) {
                    Throwable cause = e.getCause();
                    System.out.println("task failed: " + cause.getClass().getSimpleName() + ": " + cause.getMessage());
                }
            }
        }
    }
}

Output:

price = 120.0
task failed: IllegalArgumentException: sku must not be blank

The exception is thrown in a pool thread, not in the thread that calls get(). Exceptions can't jump between threads directly, so the executor stores the failure, and get() throws an ExecutionException whose cause is the original exception. Handling ExecutionException itself tells you only that "the task failed"; getCause() tells you why. (ExecutorService implements AutoCloseable since Java 19, so try-with-resources shuts the pool down and waits for the tasks.)

Other JDK wrappers that work the same way:

Guidelines for Chaining

• Always pass the cause when you throw from a catch block. It costs one argument and preserves everything needed for debugging.
• Add context in the new message. Describe what the current layer was trying to do ("could not load order ORD-1001"), not just what the cause already says.
• Translate at layer boundaries, not at every method. Wrapping the same failure at every level creates long chains of near-identical exceptions. Wrap where the abstraction changes — for example from persistence to business logic.
• Don't log and rethrow. If you wrap and throw, let the code that finally handles the exception log it once, with the full chain. Logging at every level produces duplicate entries for one failure.
• Give custom exceptions a (message, cause) constructor so they can participate in chains.
• Decide based on the root cause when it matters, but match on types (instanceof) or structured data (getSQLState(), error codes), never on parsing message text, which can change between library versions.