Exception handling

Most programs so far assumed the happy path. The array index was in range, the number you divided by was not zero, the file you opened was really there. Real programs cannot count on that. This lesson is about what Java does when something goes wrong while a program is running, and how you take that moment back into your own hands.

When the program hits a wall#

Start with the failure, because the failure is the reason this topic exists. Here is a tiny program that divides two numbers, and the second number happens to be zero. A whole number divided by zero has no answer, so Java refuses to continue.

Press Run. The first line prints, then the program stops on the division and reports what went wrong. That report is what you see when the program throws an exception and nothing is there to catch it.

Notice two things. The first println ran, so the program really was alive and moving. And the last println never ran: the moment the division failed, Java abandoned the rest of main. An exception is an object Java creates at the instant something goes wrong while the program runs. It interrupts the normal flow and travels back up through the methods that are running, looking for code willing to handle it. If it finds none, the program stops and prints the report you just saw.

Key idea

An exception is Java's way of signalling “I cannot do what you asked” in the middle of running. Left unhandled, it stops the program where it stands.

Catching it: try and catch#

Crashing is rarely what you want. A banking app that quits because one customer typed a zero is a bad banking app. Java lets you wrap a risky piece of code, attempt it, and if it throws, jump to a recovery plan instead of stopping. That is try and catch. Here is the same division, now caught. Step through it and watch the jump from the division straight into the catch block.

Read the shape of it. The try block holds the code that might fail. If everything inside it succeeds, the catch block is skipped entirely. If any line inside try throws, Java stops that block at once and looks at the catch. Here the division throws an ArithmeticException, and the catch handles exactly that type, so control jumps inside it. The line that would have printed the share never runs, just like before, but now the program does not crash. It prints Could not divide: / by zero and carries on to the last line.

What is the e?#

The (ArithmeticException e) after catch looks like a method parameter, and it works like one. When the exception is thrown, Java hands the exception object to your catch block under the name you chose, here e. That object carries useful information. The most common thing to ask it is e.getMessage(), which returns the text describing what went wrong, here / by zero. You will meet e.printStackTrace() later in this lesson.

It prints A, C and D. A prints normally. Reading scores[2] throws, so the rest of the try block, including B, is skipped, and the catch prints C. After the catch the program carries on as usual and prints D.

Recovering from bad input#

Two earlier lessons promised this moment. In wrapper classes, Integer.parseInt threw a NumberFormatException on text like 4o. With a try inside the loop, one bad entry no longer stops the whole program:

The program prints Skipping 4o: For input string: "4o" and then Total: 39. Because the try sits inside the loop, a failure ends only the current pass. The loop moves on to 20 and adds it.

In Scanner and console applications, nextInt() threw an InputMismatchException when someone typed a word. You can catch that too, and ask again. One detail matters: when nextInt()fails, the bad token stays in the scanner's buffer, so the next nextInt() would fail on it again. The catch has to read it out of the way with next().

1import java.util.InputMismatchException;
2import java.util.Scanner;
3 
4public class Main {
5    public static void main(String[] args) {
6        Scanner sc = new Scanner(System.in);
7        int age = 0;
8        boolean done = false;
9 
10        while (!done) {
11            System.out.println("How old are you?");
12            // TODO: catch the InputMismatchException that nextInt throws,
13            // throw away the bad token with sc.next(), and say it was not a number
14            age = sc.nextInt();
15            done = true;
16        }
17 
18        System.out.println("Next year you will be " + (age + 1) + ".");
19    }
20}

Several catch blocks, and multi-catch#

One try can be followed by several catch blocks, each naming a different type. Java checks them from top to bottom and runs the first one whose type matches the exception. That lets you respond differently to different failures:

8 works and prints 100 / 8 = 12. zero fails inside parseInt, so the first catch runs. 0 parses fine but fails at the division, so the second one runs. At most one catch runs for each exception.

When two failures deserve the same response, one catch can name both types, separated by |. This is called a multi-catch:

The two failures now share one message, and e.getMessage() still tells them apart: For input string: "zero" for the first and / by zero for the second.

finally: the code that always runs#

Often there is something you must do whether the risky code succeeded or failed: close a file, release a connection, switch a sign back off. Putting it after the try is not safe, because if the catch itself returns or throws, that line is skipped. Java gives you a third block for exactly this. finally runs no matter how the try ended.

Here nothing failed, so the catch was skipped, but the finally still ran. Now watch what happens when the try does throw. The catch runs, and then the finally runs after it, every single time.

Trace the order carefully. The division throws, and Java leaves the tryat once, so “This line never runs” is skipped. Java finds the matching catch and runs it, which prints the recovery message. Only then, on the way out of the whole structure, does the finallyrun and print “Closing the file”. finally always runs, and it runs last, after the try or the catch has done its part.

Key idea

try holds the risky work. catch is the recovery plan for when it fails. finally is the cleanup that happens either way. A plain try needs at least one catch or a finally after it.

finally runs even when the try or the catch leaves the method with return. Java works out the value to return, runs the finally block, and only then hands the value back to the caller.

For check(5), the try reaches return "ok 2", but finally prints its line before main receives the value and prints ok 2. For check(0), the division throws, the catch returns "failed", and again finally prints first. So finally for always comes before the returned value.

try-with-resources is a try too#

You have used try-with-resources since reading files. It is a try statement whose parentheses open a resource, such as a reader or a writer, and Java closes that resource when the block ends, as if you had written the close() in a finally yourself. That is why it can stand alone with no catch. It may also have catch blocks of its own, and that is the careful way to deal with a missing file, instead of throws IOException on main:

This page's disk has no settings.txt, so opening it throws a FileNotFoundException. That is a kind of IOException, so the catch handles it and prints Could not read settings: settings.txt (No such file or directory), and the program goes on with its defaults. main no longer says throws IOException, because nothing escapes it. When a reader did open, Java closes it before any catch or finally block of the same statement runs.

Two families: checked and unchecked#

Not all exceptions are treated the same by the compiler. Java sorts them into two families, and the family decides whether you must deal with an exception before your code will even compile.

Every exception class descends from one class, Throwable. Below it the family tree splits.

• Error covers serious trouble inside the JVM itself, such as the StackOverflowError you met in recursion, or running out of memory. Programs do not try to catch these.
• RuntimeException and everything below it are unchecked exceptions. These are the runtime mistakes you have already met: dividing by zero, a bad index, a null reference. The compiler lets your code compile without a single try around them, on the theory that they signal bugs you should fix rather than failures you must routinely expect.
• Every other exception is a checked exception, one the compiler insists you account for. The classic example is IOException, the failure that hangs over every file operation. A file can be missing or locked, or the disk can be full, and none of that is a bug in your code. Because such failure is expected, Java makes you say, in the code, that you have either handled it or passed it on.

Forget to handle a checked exception, and the program does not compile. This read-along block shows what javac says:

Main.java:7: error: unreported exception FileNotFoundException; must be caught or declared to be thrown
        FileReader r = new FileReader("data.txt");
                       ^
1 error

That is not a crash at run time. The compiler refuses the program before it ever runs, points at the call, and names the checked exception that is going unhandled: FileNotFoundException, the exception that FileReader's constructor declares. The fix is either to wrap the call in a try and catch, or to declare the exception with throws, as the file lessons did and as the next sections explain.

The tree also explains which catch runs. A catch handles the type it names and every type below it in the tree, so catch (IOException e) also catches a FileNotFoundException. That is why the more specific catch must come first. If a catch for a parent type came first, the one for its child could never run, and javac refuses with a message such as error: exception NumberFormatException has already been caught.

Raising one yourself: throw#

So far exceptions have been thrown for you, by the division operator or parseInt. You can also throw one deliberately. This is how you guard your own methods against being asked to do something that makes no sense. If a withdrawal amount is negative, that is not a calculation to perform quietly. It is a caller's mistake, and saying so loudly is kinder than carrying on.

The keyword is throw, followed by a new exception object. Here a method refuses a negative amount by throwing an IllegalArgumentException, an unchecked exception that means “you passed me an argument I cannot accept”.

Follow the two calls. The first, withdraw(balance, 30), passes the check and returns 70, which prints. The second, withdraw(balance, -5), enters the if, runs throw, and the method ends right there without returning anything. The exception flies out of withdraw and back into main, where the surrounding try catches it and prints Caught: amount cannot be negative. The text you pass to the constructor is exactly what getMessage() later returns.

1public class Main {
2    public static void main(String[] args) {
3        int[] tries = {21, 35, 18, 4};
4        for (int i = 0; i < tries.length; i++) {
5            try {
6                setTarget(tries[i]);
7                System.out.println("Target set to " + tries[i]);
8            } catch (IllegalArgumentException e) {
9                System.out.println("Rejected: " + e.getMessage());
10            }
11        }
12    }
13 
14    static void setTarget(int degrees) {
15        // TODO: when degrees is below 10 or above 30, throw an
16        // IllegalArgumentException with the message "<degrees> is outside 10 to 30"
17    }
18}

Passing it up: throws#

Catching is not the only response to a checked exception. Sometimes the method you are writing is not the right place to recover. A small method that reads a file has no idea what the program as a whole should do when the file is missing. Rather than guess, it can decline to handle the failure and let it travel up to a caller who does know. The way it says so is throws on its header.

Read how the responsibility moves. loadConfig opens a file, which can throw a checked IOException. It chooses not to catch it. By writing throws IOExceptionafter its parameter list, it tells its callers: “I might let this exception out, so you must be ready for it.” That is what satisfies the compiler. Up in main, the call to loadConfig is wrapped in a try, so when the file is missing, as it is on this page's disk, the exception lands there and main carries on with default settings. Step through it and watch the loadConfig frame disappear from the call stack as the exception leaves it.

Key idea

For a checked exception you have two honest choices: handle it here with try and catch, or declare throws and pass it to whoever called you. The compiler makes you pick one.

Your own exception classes#

Java's exception classes cover common failures, but they cannot name the failures of your own program. A banking app wants to say InsufficientFundsException, which tells a reader far more than a general IllegalArgumentException. An exception class is an ordinary class that extends Exception, for a checked exception, or RuntimeException, for an unchecked one. Most need only a constructor that passes the message up to the parent with super, as you did in inheritance:

The first withdrawal works. The second asks for more than the balance, so withdraw throws, the line Withdrew 500 is skipped, and main prints Refused: balance is 70, cannot withdraw 500, then Balance: 70. Because InsufficientFundsException extends Exception, it is checked: withdraw must declare it with throws, and every caller must catch it or declare it in turn.

• Extend Exception when a caller can reasonably recover and should be made to think about it, like a withdrawal that is too large.
• Extend RuntimeException when the failure means the caller broke the rules, like passing a negative amount.
• End the class name with Exception, so anyone reading a catch knows what it is at once.

Reading a stack trace#

You learned to read a stack trace in reading errors and debugging: the first line says what went wrong, and the first at line that names your own file says where. Traces get longer when the failure happens several method calls deep. In this program, main calls start, which calls compute, and the deepest one divides by zero.

Step to the division and look at the call stack: three frames, compute on top of start on top of main. The stack trace the program prints is a written copy of that stack, read from the top down:

1. 1The first line names the exception and its message: ArithmeticException: / by zero. That is what went wrong. Always read this line first.
2. 2The topmost at line is where it went wrong: Main.compute(Main.java:11). The failure happened inside compute, at line 11 of the file. This is almost always the line you want to look at.
3. 3Each at line below it is the caller of the one above. compute was called by start on line 7, which was called by main on line 3. Reading downwards walks you back out through the chain of calls, to where the program began.

So a stack trace is a story told backwards. The top is the scene of the failure, and each line beneath it is who sent you there.

The same report, from inside a catch#

You do not have to crash to see a trace. Inside a catch block, e.printStackTrace() prints the same report while the program keeps running. It writes to standard error, so in the console here its lines are marked with !:

The report starts with java.lang.ArithmeticException: / by zero, without the Exception in thread "main" part, because the exception did not end the program. Still running. follows it.

Caused by: one exception wrapped in another#

A method sometimes catches a low-level exception and throws a clearer one in its place, passing the original along as the cause. Most exception classes have a constructor that takes a message and a cause. Here loadTheme turns a missing file into an IllegalStateException, and nothing catches it:

The trace now has two parts. The first is the exception that ended the program, thrown on line 15. The second starts with Caused by: and is the original FileNotFoundException, thrown where the file was opened, on line 12. Its last line, ... 1 more, is shorthand: the remaining frame is the same as the last frame of the part above (main, line 7), so Java does not repeat it. Run in a terminal, real Java prints the same trace with the library's own lines added:

When a trace has a Caused by section, the real problem is usually in the last one: here, a file that is not there. The outer exception tells you what the program was trying to do when it hit that problem.

Putting it together#

Here is one slightly larger example that uses the pieces together: a method that writes a real file and passes its IOException up with throws, an IllegalArgumentException of its own for a bad file name, two catch blocks, and a finally. The loop tries a good name and an empty one.

Trace it through. The first pass saves Sales: 12 into report.txt (watch it appear in the Files section), prints Saved., and then the finally line. On the second pass, save("", ...) finds the empty name, so throw raises an IllegalArgumentException before any file is touched. The first catch handles it and prints the refusal, the finally runs again, and the loop ends. The IOException catch is there for a real disk failure, which did not happen in this run.

Further reading#

• The exceptions tutorial on dev.java, the official Java learning site
• Throwable in the Java SE 25 API documentation, with getMessage, getCause and the stack trace format, Caused by included
• Exceptions in the Java Language Specification, chapter 11, the exact rules for checked and unchecked exceptions