Exception Handling

Custom Exception Classes

15 min Lesson 7 of 14

Custom Exception Classes

The exceptions Java ships with — IllegalArgumentException, IOException, NullPointerException — are generic. When you read a stack trace that says IllegalArgumentException: invalid value you still have to guess which value was invalid and why. Custom exception classes solve this: they give a precise name to the problem, they live in your domain, and they can carry extra context that generic exceptions cannot.

Why Create Your Own Exceptions?

Meaningful names. InsufficientFundsException communicates the problem instantly; RuntimeException: balance too low does not.
Catch selectively. Callers can catch only the exact failure they know how to handle, without accidentally silencing unrelated problems.
Carry domain data. A custom class can store the account number, the requested amount, and the current balance — not just a string message.
Cleaner APIs. A method signature like throws InsufficientFundsException documents intent far better than throws Exception.

Extending Exception vs. RuntimeException

This is the most important design choice. The rule from Lesson 4 still applies:

Extend Exception (checked) when the caller should handle the failure — file not found, network timeout, business-rule violations the caller can recover from.
Extend RuntimeException (unchecked) when the failure is a programming mistake — invalid argument, wrong state, broken contract — that callers should not normally catch.

Domain logic errors are usually checked. If your bank transfer method can legitimately fail because a user has insufficient funds, that is a recoverable situation the UI must handle — so InsufficientFundsException extends Exception is the right choice. If an internal utility receives a null it was never supposed to receive, extends RuntimeException is cleaner.

The Minimal Pattern

Every custom exception needs at minimum a constructor that accepts a message and forwards it to the parent:

public class InsufficientFundsException extends Exception {

    public InsufficientFundsException(String message) {
        super(message);
    }
}

That is all you need to throw it and catch it by name:

public void withdraw(double amount) throws InsufficientFundsException {
    if (amount > balance) {
        throw new InsufficientFundsException(
            "Cannot withdraw " + amount + "; balance is " + balance
        );
    }
    balance -= amount;
}

Adding a Cause Constructor

Always provide a constructor that accepts a Throwable cause. This lets you wrap lower-level exceptions without losing the original stack trace — a practice covered in Lesson 6 (rethrowing).

public class DataAccessException extends RuntimeException {

    public DataAccessException(String message) {
        super(message);
    }

    public DataAccessException(String message, Throwable cause) {
        super(message, cause);
    }
}

Storing Domain-Specific Data

A custom class can hold any fields that help callers react intelligently to the failure:

public class InsufficientFundsException extends Exception {

    private final double requested;
    private final double available;

    public InsufficientFundsException(double requested, double available) {
        super("Requested " + requested + " but only " + available + " available");
        this.requested = requested;
        this.available = available;
    }

    public double getRequested() { return requested; }
    public double getAvailable() { return available; }
    public double getShortfall()  { return requested - available; }
}

Now a caller can present a helpful message to the user without parsing a string:

try {
    account.withdraw(500.00);
} catch (InsufficientFundsException e) {
    System.out.println("Transfer failed. You need " + e.getShortfall()
        + " more to complete this transaction.");
}

Building a Small Exception Hierarchy

For a larger application, group related exceptions under a common base so callers can catch broadly or narrowly:

// Base class for all payment-related failures
public class PaymentException extends Exception {
    public PaymentException(String message) { super(message); }
    public PaymentException(String message, Throwable cause) { super(message, cause); }
}

// Specific subtypes
public class InsufficientFundsException extends PaymentException {
    public InsufficientFundsException(double shortfall) {
        super("Short by " + shortfall);
    }
}

public class CardDeclinedException extends PaymentException {
    public CardDeclinedException(String reason) {
        super("Card declined: " + reason);
    }
}

A payment gateway handler can catch all payment problems with catch (PaymentException e), while a refund module that only cares about declined cards can catch CardDeclinedException specifically.

Keep the hierarchy shallow. One level of specialisation (base + concrete subtypes) is almost always enough. Deep hierarchies are hard to navigate and rarely add value.

Naming Convention

Every custom exception class name should end with Exception — ValidationException, OrderNotFoundException, RateLimitExceededException. Java developers expect this; breaking the convention confuses readers.

Do not extend Error or Throwable directly. Error is reserved for JVM-level failures (out of memory, stack overflow). Extending Throwable bypasses the checked/unchecked distinction entirely and breaks assumptions throughout the language. Always extend Exception or RuntimeException.

Summary

Custom exception classes make your code self-documenting and easier to maintain. Extend Exception for recoverable domain failures, extend RuntimeException for programming errors. Always provide a message constructor and a cause constructor. Add fields when callers need structured data beyond a message string. Keep hierarchies flat — a well-named base and a handful of concrete subtypes is the right shape for most applications.