Custom Exceptions

Java's built-in exceptions cover generic problems like invalid arguments or null references, but real applications often have domain-specific failure conditions — an insufficient account balance, an invalid order state, a seat that is already booked. Custom exceptions let you represent these situations as distinct, self-documenting types instead of overloading generic exceptions or plain error codes.

Why it matters

A generic Exception("error") tells the caller nothing. A named exception such as InsufficientFundsException says exactly what went wrong, can carry the relevant data, and can be caught separately from everything else. Well-chosen custom exceptions make an application's failures part of its design.

Extending Exception vs RuntimeException

A custom exception is created by extending an existing exception class. Extending Exception creates a checked exception, forcing every caller to handle it or declare it — appropriate when callers can reasonably be expected to recover, such as a business rule violation that the calling code should specifically respond to. Extending RuntimeException creates an unchecked exception, which callers are not forced to handle — appropriate for programming errors or conditions that indicate a bug rather than an expected, recoverable situation.

Calling super(message)

A well-designed custom exception provides at least one constructor that accepts a message and passes it to the parent class using super(message), so that getMessage() works correctly and the message appears in stack traces. It's also good practice to provide a constructor accepting a Throwable cause, passed as super(message, cause), so the original underlying exception isn't lost when you wrap and re-throw it as your custom type.

• public InsufficientFundsException(String message) { super(message); }
• public InsufficientFundsException(String message, Throwable cause) { super(message, cause); }
• Naming convention: custom exception class names should end in "Exception".

When to Make an Exception Checked vs Unchecked

Choose checked when failure is an expected, recoverable part of the domain and callers genuinely need to be reminded to handle it — for example, a custom SeatAlreadyBookedException in a booking system, which calling code should catch and respond to (offer another seat). Choose unchecked when the failure represents a violated precondition or programming bug that shouldn't force every caller up the chain to add boilerplate handling, such as a custom InvalidConfigurationException thrown when a developer misconfigures a service at startup.

Example

class InsufficientFundsException extends Exception {
    public InsufficientFundsException(String message) {
        super(message);
    }
}

public class CustomExceptionDemo {
    static void withdraw(double balance, double amount) throws InsufficientFundsException {
        if (amount > balance) {
            throw new InsufficientFundsException(
                "Cannot withdraw " + amount + "; balance is only " + balance);
        }
        System.out.println("Withdrawal successful: " + amount);
    }

    public static void main(String[] args) {
        try {
            withdraw(100.0, 250.0);
        } catch (InsufficientFundsException e) {
            System.out.println("Transaction failed: " + e.getMessage());
        }
    }
}

Transaction failed: Cannot withdraw 250.0; balance is only 100.0

Exercise

Create a checked exception InvalidCouponException. discountFor should return 10 for the code SAVE10 and throw the exception for any other code, with a message naming the code.

Expected output: 10 then Invalid coupon: FREE

// TODO: class InvalidCouponException extends Exception, with a message constructor

public class CouponDemo {

    static int discountFor(String code) throws InvalidCouponException {
        // TODO: return 10 for "SAVE10", otherwise throw the exception
        return 0;
    }

    public static void main(String[] args) {
        try {
            System.out.println(discountFor("SAVE10"));
            System.out.println(discountFor("FREE"));
        } catch (InvalidCouponException e) {
            System.out.println(e.getMessage());
        }
    }
}

class InvalidCouponException extends Exception {
    InvalidCouponException(String message) {
        super(message);
    }
}

public class CouponDemo {

    static int discountFor(String code) throws InvalidCouponException {
        if ("SAVE10".equals(code)) {
            return 10;
        }
        throw new InvalidCouponException("Invalid coupon: " + code);
    }

    public static void main(String[] args) {
        try {
            System.out.println(discountFor("SAVE10"));
            System.out.println(discountFor("FREE"));
        } catch (InvalidCouponException e) {
            System.out.println(e.getMessage());
        }
    }
}

Quick quiz

Interview questions