Exceptions: Handling Errors Properly

Things go wrong in real programs: a file is missing, the network drops, a user types "abc" where a number is expected, a database refuses a connection. A program that cannot deal with failure is a demo, not software. The question is how a language lets you deal with it.

Older languages used return codes: every function returns a status, and every caller must remember to check it. People forget, and the failure is silently ignored. Java's answer is the exception: a failure that cannot be ignored by accident, because if nobody handles it, the program stops.

• What an exception is and how it travels through the call stack.
• The exception hierarchy, and checked versus unchecked exceptions.
• try, catch, finally and try-with-resources.
• How to write and chain custom exceptions.
• What good exception design looks like, and the common anti-patterns.

When method main calls process, which calls parse, the JVM keeps a call stack: a stack of method calls in progress. Normally each method returns to the one that called it. When something goes wrong, parse can throw an exception object instead. The JVM then looks for a handler in parse. If there is none, parse is abandoned and the JVM looks in process, then in main, unwinding the stack one call at a time. If it reaches the top without finding a handler, the thread dies and prints a stack trace.

// File: Main.javapublic class Main {    static int parseAge(String text) {        int age = Integer.parseInt(text);          // may throw NumberFormatException        if (age < 0) {            throw new IllegalArgumentException("age cannot be negative: " + age);        }        return age;    }    static String describe(String text) {        System.out.println("describe: start");        int age = parseAge(text);        System.out.println("describe: finished");  // skipped when parseAge throws        return "age " + age;    }    public static void main(String[] args) {        System.out.println(describe("29"));        try {            System.out.println(describe("abc"));        } catch (NumberFormatException e) {            System.out.println("handled: " + e.getMessage());        }        try {            describe("-5");        } catch (IllegalArgumentException e) {            System.out.println("handled: " + e.getMessage());        }    }}

describe: startdescribe: finishedage 29describe: starthandled: For input string: "abc"describe: starthandled: age cannot be negative: -5

For "abc", the output shows describe: start but never describe: finished: the exception left describe immediately. The handler in main caught it and the program continued. An exception is a non-local jump up the call stack to the nearest matching catch.

All exceptions are objects of classes that descend from java.lang.Throwable.

Throwable |-- Error                      serious JVM-level problems (OutOfMemoryError, StackOverflowError) `-- Exception      |-- IOException, SQLException, ...     checked exceptions      `-- RuntimeException                   unchecked exceptions           |-- NullPointerException           |-- IllegalArgumentException, IllegalStateException           |-- ArrayIndexOutOfBoundsException, ArithmeticException, ...           `-- (your own unchecked exceptions)

The split that matters in practice is checked versus unchecked:

Error and its subclasses signal problems with the JVM itself, such as running out of memory. Applications should not normally catch them, because there is generally nothing sensible they can do.

Oracle's tutorial gives a guideline: if a client can reasonably be expected to recover from an exception, make it a checked exception; if a client cannot do anything to recover, make it an unchecked exception. The reasoning is that the exceptions a method can throw are part of its public interface, so callers should be forced to think about them.

That is the original design intention. Experience has produced a real debate:

For checked exceptions: they make failure modes visible in the method signature and force callers to decide. For genuinely recoverable situations (a file the user chose does not exist, so ask for another) this is useful.

Against: they spread through code. A low-level SQLException propagates through every layer's throws clause, leaking implementation details. They often tempt developers to write an empty catch just to make the compiler quiet. They do not work well with lambdas, because functional interfaces such as Function do not declare checked exceptions (article 15). And many failures are not recoverable by the immediate caller anyway.

Practical outcome: modern Java frameworks lean towards unchecked exceptions. Spring, for example, wraps the checked SQLException of JDBC in its own unchecked data-access exceptions (article 34). A good working rule: use unchecked exceptions for programming errors and for failures that the calling code cannot meaningfully fix, and consider a checked exception only when you are designing an API where callers can and should handle a specific, expected condition. The Oracle tutorial adds a warning worth remembering: do not make an exception unchecked just because you do not want to be bothered with declaring it.

// File: Main.javapublic class Main {    static String classify(String input) {        try {            int n = Integer.parseInt(input);            return "number " + (100 / n);        } catch (NumberFormatException e) {            return "not a number";        } catch (ArithmeticException e) {            return "cannot divide by zero";        } finally {            System.out.println("finally ran for '" + input + "'");        }    }    @SuppressWarnings("finally")    static int returnInFinally() {        try {            return 1;        } finally {            return 2;            // overrides the earlier return: a trap        }    }    public static void main(String[] args) {        System.out.println(classify("4"));        System.out.println(classify("x"));        System.out.println(classify("0"));        System.out.println(returnInFinally());        try {            Object o = "text";            Integer wrong = (Integer) o;        } catch (ClassCastException | NullPointerException e) {    // multi-catch            System.out.println("multi-catch: " + e.getClass().getSimpleName());        }    }}

finally ran for '4'number 25finally ran for 'x'not a numberfinally ran for '0'cannot divide by zero2multi-catch: ClassCastException

How it works:

• The try block holds the code that may throw.
• Each catch handles one kind of exception. The first catch whose type matches (the exception's class or a superclass) runs. Put more specific types first, because a catch for a superclass such as Exception placed first would make the later ones unreachable, and the compiler rejects that. A multi-catch (A | B) shares one handler.
• finally runs whether or not an exception occurred, for clean-up. As the output shows, it ran in all three calls. Avoid return inside finally: it overrides the normal return and can swallow exceptions, as returnInFinally demonstrates.

Files, database connections and network sockets are resources: they hold something outside the JVM and must be closed, or they leak. Before Java 7 this meant try/finally, which is easy to get wrong. try-with-resources closes them for you. Oracle's tutorial states that any object implementing AutoCloseable (which includes everything implementing Closeable) can be used as a resource, and that each resource is closed at the end whether the statement completes normally or abruptly.

// File: Main.javapublic class Main {    static class Resource implements AutoCloseable {        private final String name;        private final boolean failOnClose;        Resource(String name, boolean failOnClose) {            this.name = name;            this.failOnClose = failOnClose;            System.out.println("open " + name);        }        void use() {            System.out.println("use " + name);        }        @Override        public void close() {            System.out.println("close " + name);            if (failOnClose) {                throw new IllegalStateException("close failed for " + name);            }        }    }    public static void main(String[] args) {        try (Resource first = new Resource("A", false);             Resource second = new Resource("B", false)) {            first.use();            second.use();        }        System.out.println("---");        try (Resource only = new Resource("C", true)) {            only.use();            throw new IllegalArgumentException("problem while using C");        } catch (IllegalArgumentException e) {            System.out.println("caught: " + e.getMessage());            for (Throwable suppressed : e.getSuppressed()) {                System.out.println("suppressed: " + suppressed.getMessage());            }        }    }}

open Aopen Buse Ause Bclose Bclose A---open Cuse Cclose Ccaught: problem while using Csuppressed: close failed for C

Two guarantees are visible. First, resources are closed in the reverse order of creation (B before A), because a later resource may depend on an earlier one. Second, when both the body and close() throw, the original exception from the body is the one you receive. The exception from close() is attached to it as a suppressed exception, retrievable with getSuppressed(), instead of replacing it. With a hand-written finally, the second exception would have hidden the first, which is the leak and confusion the tutorial warns about. The rule: if it has a close() method, open it in a try-with-resources.

You throw an exception with throw new SomeException("message"). A method that can throw a checked exception must declare it with throws, and the caller must catch it or declare it in turn:

static String readConfig(Path path) throws IOException {   // callers must handle IOException    return Files.readString(path);}

Unchecked exceptions need no declaration, though documenting them in the Javadoc is good practice.

Before writing your own, use the standard ones where they fit:

When your domain has failures that deserve a name and extra information, define your own exception. Extend RuntimeException (unchecked) unless you have decided that callers must handle it, and keep it small. Most importantly, when you catch a lower-level exception and throw a higher-level one, keep the original as the cause. This is called exception chaining.

// File: Main.javapublic class Main {    static class DataAccessFailure extends RuntimeException {        DataAccessFailure(String message, Throwable cause) {            super(message, cause);        }    }    static class ApplicationNotFoundException extends RuntimeException {        private final long id;        ApplicationNotFoundException(long id) {            super("job application " + id + " was not found");            this.id = id;        }        long id() {            return id;        }    }    // Pretend low-level code that throws a technical exception    static String loadFromStorage(long id) throws java.io.IOException {        throw new java.io.IOException("disk read error for record " + id);    }    static String findApplication(long id) {        if (id <= 0) {            throw new ApplicationNotFoundException(id);        }        try {            return loadFromStorage(id);        } catch (java.io.IOException e) {            throw new DataAccessFailure("could not load application " + id, e);   // keep the cause        }    }    public static void main(String[] args) {        try {            findApplication(0);        } catch (ApplicationNotFoundException e) {            System.out.println("not found: id=" + e.id() + " (" + e.getMessage() + ")");        }        try {            findApplication(7);        } catch (DataAccessFailure e) {            System.out.println(e.getMessage());            System.out.println("caused by: " + e.getCause().getClass().getSimpleName() + ": " + e.getCause().getMessage());        }    }}

not found: id=0 (job application 0 was not found)could not load application 7caused by: IOException: disk read error for record 7

The higher layer sees a meaningful, domain-level exception (DataAccessFailure, ApplicationNotFoundException) and not a raw IOException from the layer below. But the original IOException survives as the cause, so the full story appears in the stack trace when you log it. Always pass the cause: throwing a new exception without it destroys the evidence you need to debug. In the REST API project you will map ApplicationNotFoundException to an HTTP 404 response in one central place (article 33).

Do:

• Fail fast. Validate arguments at the start of a method and throw immediately, rather than letting bad data travel and fail somewhere confusing.
• Be specific. Catch the narrowest exception you can handle, and throw the most precise one that fits.
• Include context in the message: what you were doing and the values involved (but never passwords or secrets).
• Preserve the cause when wrapping.
• Handle an exception at the level that can do something about it, which is often much higher than where it was thrown. Let it propagate until then.
• Use try-with-resources for anything closeable.
• Log an exception once, at the place where you handle it (see article 22).

Do not:

• Swallow exceptions. catch (Exception e) { } hides failures, and the program carries on in an unknown state. If you truly intend to ignore one, say why in a comment, and ideally log it.
• Catch Exception or Throwable broadly just to make errors disappear. At the very top of a thread or request, a catch-all that logs and returns an error response is acceptable. In the middle of business logic it is not.
• Both log and rethrow the same exception at every layer. The same stack trace then appears five times in the log, making the real problem hard to find.
• Use exceptions for normal control flow, such as using an exception to leave a loop or to signal "not found" in a hot path. They are harder to read and slower than ordinary conditions.
• Return null to indicate failure when an exception, an empty result or an Optional communicates better (article 17).
• Catch an Error (such as OutOfMemoryError) and carry on as if nothing happened.

For failures that are expected and frequent (user input that does not parse, a search with no result), a return type that models the alternatives can be a clearer API than an exception. Remember the sealed ParseResult from article 9. The skill is to choose: exceptions for exceptional or programming-error conditions, and ordinary return values for ordinary outcomes.

• Empty catch blocks.
• Catching Exception when a specific exception is meant.
• Losing the cause when wrapping an exception.
• Logging and rethrowing at every level.
• Putting return in finally.
• Forgetting to close resources, or closing them manually in the wrong order.
• Using printStackTrace() as error handling in application code. It goes to standard error and bypasses your logging.
• Over-using checked exceptions, forcing every caller to handle something they cannot fix.
• Throwing Exception or RuntimeException directly, which gives callers nothing specific to catch.

try (BufferedReader reader = new BufferedReader(new FileReader(path))) {    return reader.readLine();}

• Next: Lists and Sets begins the collections module.
• For using exceptions with files: File I/O and Serialization.
• For reading stack traces and logging: Debugging: Errors, Stack Traces, the Debugger and Logging.