Java Reference ยท java.lang
Checked vs. unchecked exceptions in Java
How Java splits exceptions into checked, unchecked and errors, what the compiler enforces, and practical guidance for choosing between them in your own APIs.
Java divides throwable types into three groups. Checked exceptions are subclasses of Exception that are not subclasses of RuntimeException; the compiler requires every method that may throw one to catch it or declare it with throws. Unchecked exceptions are RuntimeException and its subclasses; they need no declaration. Errors (subclasses of Error) signal serious JVM-level problems and are also unchecked.
The distinction is enforced only by the compiler; at run time all of them are ordinary Throwable objects. The design question is which kind to throw from your own code, and the answer depends on who can reasonably recover.
// checked: the signature is part of the contract void load(Path p) throws IOException { /* ... */ } // unchecked: no declaration required void setAge(int age) { if (age < 0) throw new IllegalArgumentException("age < 0"); }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
How the rules work
- Declaration: a method that can throw a checked exception must list it (or a superclass) in
throws, unless it catches it. Overriding methods may declare fewer or narrower checked exceptions, never broader ones. - Reachability: catching a checked exception that the
trybody cannot throw is a compile error (except forExceptionandThrowable). Catch clauses must go from subclass to superclass. - Unchecked exceptions can be thrown and caught anywhere without any declaration, although you may list them in
throwsas documentation. - Errors should almost never be caught or thrown by application code.
Choosing for your own APIs
| Situation | Prefer |
|---|---|
| Caller made a programming mistake (null, bad index, wrong state) | Unchecked: IllegalArgumentException, IllegalStateException, NullPointerException |
| Failure the caller can realistically handle or retry (I/O, network, parsing external data) | Checked, or a result type such as Optional |
| Failure nobody up the stack can fix (misconfiguration, broken invariant) | Unchecked |
| A low-level checked exception crossing a lambda or layer boundary | Wrap in an unchecked exception, keep the cause |
Usage notes
- Always keep the cause when wrapping:
new ConfigException("...", e). Dropping it destroys the stack trace that explains the failure. - Checked exceptions do not work with standard functional interfaces (
Function,Runnable,Supplier, ...), which is why many streams-heavy code bases favor unchecked exceptions. Theuncheckedhelper in the second example is one way to bridge the gap. - Do not declare
throws Exceptionon public APIs: it forces callers to catch everything and says nothing about what can go wrong. - Avoid checked exceptions that nobody can handle. If every caller just rethrows or logs them, make the exception unchecked.
- Document unchecked exceptions in the Javadoc (
@throws) even though the compiler does not require it. - Checked exceptions and overriding: an interface method with no
throwsclause cannot be implemented with a method that throws a checked exception. - Other languages (Kotlin, Scala, C#) have no checked exceptions. Java's approach is debated, but the rules above are the common practice in the Java ecosystem.