The Exception Hierarchy

Why this matters

• The checked-versus-unchecked distinction decides whether the compiler forces a caller to deal with your failure, which is an API design decision rather than a technical one.
• Catching the wrong branch of the hierarchy turns a recoverable problem into a hidden one, or a fatal problem into a corrupted program that keeps running.
• Reading a stack trace correctly is the single highest-value debugging skill, and most people read it in the wrong direction.

The hierarchy

Checked versus unchecked

The compiler's rule is purely structural: is the type a RuntimeException or an Error? If not, it is checked.

// Checked: the compiler will not let you ignore it
public String readConfig(Path path) throws IOException {
    return Files.readString(path);
}

// Unchecked: no declaration required, though documenting it is good practice
public void setAge(int age) {
    if (age < 0) {
        throw new IllegalArgumentException("Age cannot be negative: " + age);
    }
    this.age = age;
}

Common exceptions and what they really mean

Reading a stack trace

Exception in thread "main" java.lang.IllegalStateException: Cart is empty
	at com.prepzone.cart.Cart.checkout(Cart.java:47)
	at com.prepzone.order.OrderService.place(OrderService.java:23)
	at com.prepzone.web.OrderController.submit(OrderController.java:15)
Caused by: java.sql.SQLException: Connection timed out
	at com.prepzone.db.ConnectionPool.borrow(ConnectionPool.java:88)
	... 3 more

Wrapping preserves the cause

When you translate an exception into one appropriate for your layer, always pass the original as the cause.

public Order findById(String id) {
    try {
        return repository.load(id);
    } catch (SQLException e) {
        // Right: the original cause travels with it
        throw new OrderLookupException("Could not load order " + id, e);
    }
}

// Wrong: the SQLException and its stack trace are gone forever
catch (SQLException e) {
    throw new OrderLookupException("Could not load order " + id);
}

The second version produces a stack trace that points at your own code and tells you nothing about the timeout, the constraint violation or the deadlock that actually happened. This is the most expensive single mistake in exception handling, because it destroys the information at the exact moment you will need it.

Throwing well

public void transfer(Account from, Account to, BigDecimal amount) {
    Objects.requireNonNull(from, "from account is required");
    Objects.requireNonNull(to, "to account is required");

    if (amount.signum() <= 0) {
        throw new IllegalArgumentException("Transfer amount must be positive, was " + amount);
    }
    if (from.balance().compareTo(amount) < 0) {
        throw new InsufficientFundsException(from.id(), amount, from.balance());
    }
}

Common misreadings

• "Unchecked exceptions cannot be caught." They can be caught exactly like checked ones. The difference is only that the compiler does not insist.
• "Error and Exception are related by inheritance." Both extend Throwable, but neither extends the other.
• "NullPointerException is checked." It is a RuntimeException, so unchecked.
• "Catching Exception is a reasonable default." It hides bugs you wanted to see. Catch what you can actually handle.
• "The bottom of a stack trace is the error." The top frame is where it was thrown; the deepest Caused by is the root cause.
• "Throwing is expensive, so avoid exceptions." Filling in the stack trace costs something, which is why exceptions should not be control flow — but a genuine error path is exactly what they are for.