How to Create a Custom Exception in Java

The exception class compiles, it is thrown and caught — and e.getMessage() still prints null. This happens when you store the error text in a field of your own and forget to call super(message):

public class ValidationException extends Exception {
    private String message;

    public ValidationException(String message) {
        this.message = message; // super(message) is not called
    }
}

// somewhere in the code:
try {
    throw new ValidationException("Email must not be empty");
} catch (ValidationException e) {
    System.out.println(e.getMessage()); // Output: null
}

A custom (user-defined) exception in Java is a class that extends Exception (a checked exception) or RuntimeException (an unchecked exception). To create your own exception, declare a class whose name ends with Exception, choose the parent class and add constructors that pass the message and the cause to super(...). Everything else — getMessage(), getCause(), printStackTrace() — the class inherits.

How to create a custom exception in Java

To create a custom exception class, declare a class that extends Exception or RuntimeException and add a constructor that calls super(message). You do not have to implement any methods: a minimal user-defined exception consists of the class declaration and a single constructor.

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

Such an exception is thrown with the throw statement, and because it extends Exception, the method must declare it in its throws clause (both keywords are covered in separate lessons of this module):

public class AgeCheck {
    static void checkAge(int age) throws InvalidAgeException {
        if (age < 0 || age > 150) {
            throw new InvalidAgeException("Invalid age: " + age);
        }
        System.out.println("Age accepted: " + age);
    }

    public static void main(String[] args) {
        try {
            checkAge(25);
            checkAge(-3);
        } catch (InvalidAgeException e) {
            System.out.println("Error: " + e.getMessage());
        }
    }
}

Output:

Age accepted: 25
Error: Invalid age: -3

Extends Exception vs extends RuntimeException

Extend Exception when the calling code can and should handle the situation (the compiler will force it to), and extend RuntimeException when the exception signals a programming error or a broken method contract. The parent class decides whether your custom exception is checked or unchecked.

Which JDK classes are checked and which are unchecked is explained in the lesson Checked vs unchecked exceptions in Java.

Exception constructors: message and cause

Constructors are not inherited, so every variant you need must be declared in your class and passed on to super(...). Two are usually enough: one with a message (String message) and one with a message and a cause (String message, Throwable cause) — the second keeps the original exception when you wrap it.

The Exception class (and likewise RuntimeException) provides five constructors that you can call through super:

Here is an exception class with two constructors and exception chaining: a NumberFormatException is wrapped into a custom exception, and the original cause stays available through getCause().

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

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

public class QuantityParser {
    static int parseQuantity(String input) throws OrderProcessingException {
        try {
            return Integer.parseInt(input);
        } catch (NumberFormatException e) {
            throw new OrderProcessingException("Invalid item quantity: " + input, e);
        }
    }

    public static void main(String[] args) {
        try {
            parseQuantity("12a");
        } catch (OrderProcessingException e) {
            System.out.println(e.getMessage());
            System.out.println("Cause: " + e.getCause());
        }
    }
}

Output:

Invalid item quantity: 12a
Cause: java.lang.NumberFormatException: For input string: "12a"

Without passing e to the constructor, the second line would print Cause: null, and the Caused by: java.lang.NumberFormatException block would disappear from the stack trace — while debugging you would have to guess what actually went wrong.

A custom exception with extra fields and toString()

A custom exception can carry fields with data about the error — an error code, the invalid value, an identifier — together with getters. The handler then receives structured information, not just text. Override toString() when you need your own format for printing the exception to a log or the console.

public class MyException extends Exception {
    private final int detail;

    public MyException(int detail, String message) {
        super(message);
        this.detail = detail;
    }

    public int getDetail() {
        return detail;
    }

    @Override
    public String toString() {
        return "MyException{"
                + "detail=" + detail
                + ", message=" + getMessage()
                + "}";
    }
}

public class MyExceptionExample {
    public static void main(String[] args) {
        try {
            compute(1);
            compute(20);
        } catch (MyException e) {
            System.out.println("Caught: " + e);
        }
    }

    public static void compute(int a) throws MyException {
        System.out.println("compute(" + a + ") called");
        if (a > 10) {
            throw new MyException(a, "Value is greater than 10");
        }
        System.out.println("Normal exit.");
    }
}

Output:

compute(1) called
Normal exit.
compute(20) called
Caught: MyException{detail=20, message=Value is greater than 10}

The string concatenation "..." + e calls toString(). Without the override, the implementation from Throwable would return «fully qualified class name: message», and the last line would be Caught: MyException: Value is greater than 10 (with the package name for a class in a package). The detail field would not appear there, but it would still be available through e.getDetail().

Custom unchecked exception example: extends RuntimeException

A custom unchecked exception is created the same way, only the parent class is RuntimeException. You do not have to declare it in throws or wrap the call in try-catch: the compiler does not check it, so you catch the exception only where it actually makes sense.

public class InsufficientFundsException extends RuntimeException {
    private final long shortage;

    public InsufficientFundsException(long shortage) {
        super("Insufficient funds, short by: " + shortage);
        this.shortage = shortage;
    }

    public long getShortage() {
        return shortage;
    }
}

public class Account {
    private long balance = 100;

    public void withdraw(long amount) { // no throws needed
        if (amount > balance) {
            throw new InsufficientFundsException(amount - balance);
        }
        balance -= amount;
    }

    public static void main(String[] args) {
        Account account = new Account();
        account.withdraw(30);           // balance is 70
        try {
            account.withdraw(500);
        } catch (InsufficientFundsException e) {
            System.out.println(e.getMessage());
            System.out.println("Amount to top up: " + e.getShortage());
        }
    }
}

Output:

Insufficient funds, short by: 430
Amount to top up: 430

Remove the try-catch, and the program still compiles, but it terminates with Exception in thread "main" InsufficientFundsException: Insufficient funds, short by: 430 followed by the stack trace. With a checked exception, the same code without try-catch or throws would not compile at all.

When to create a custom exception and when to reuse a standard one

Create your own exception when the error has a meaning in your business domain (OrderNotFoundException, WrongPasswordException), when you need to pass extra data, or when the calling code must catch exactly this error separately from others. For typical contract violations, reuse a standard JDK exception — every Java developer knows what it means.

A typical use case for a custom exception is the boundary between application layers: the data access layer catches SQLException and throws its own DataAccessException with the cause, so the business logic does not depend on JDBC details. When you have many exceptions, give them a common parent (for example, ShopException and its subclasses) — then one catch handles the whole group. Remember that a catch for a subclass must come before a catch for its parent, otherwise the code does not compile: see Catching Subclasses: Order of Catch Blocks.

Where developers get tripped up

Most problems with custom exceptions are not about syntax but about lost information: an empty message, a lost cause, a badly chosen parent class. The compiler does not catch these mistakes — they show up only when you are already debugging.

• A message field of your own instead of super(message). As in the example at the top of the lesson, getMessage() and the stack trace show null. The fix: delete the field and call super(message) in the constructor.
• Losing the cause. throw new MyException("Database error") inside catch (SQLException e) throws the original exception away. Write throw new MyException("Database error", e) and declare a constructor with a Throwable cause parameter.
• Extending Throwable or Error. The first is not caught by catch (Exception e); the second is misleading, because Error means a JVM failure, not an application error.
• A name without the Exception suffix. A class named WrongPassword is formally legal, but by convention exception names end with Exception — that makes them easy to spot in code and logs.
• The serialVersionUID warning. Throwable implements Serializable, so IDEs and the compiler with the -Xlint:serial flag warn that the field is missing. It is not an error; to silence the warning, add private static final long serialVersionUID = 1L;.
• Overriding rules for throws. An overriding method cannot declare broader checked exceptions than the parent method, and that applies to your own exception classes too. These rules are covered in a separate lesson of this module on exceptions and inheritance.