Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท java.lang

The Throwable class

Reference for java.lang.Throwable, the root of all exceptions and errors: getMessage(), getCause(), stack traces, suppressed exceptions and exception chaining.

java.lang.Throwable is the superclass of everything that can be thrown with throw and caught with catch. Only Throwable objects and their subclasses are allowed there. It has two direct subclasses that split the world in two: Exception for conditions a program may want to handle, and Error for serious JVM-level problems.

A Throwable carries a message, an optional cause (the exception that triggered this one), the stack trace captured when it was created, and a list of suppressed exceptions. You rarely extend Throwable directly; you extend Exception or RuntimeException.

Java
Throwable t = new Throwable("something happened");
t.getMessage();       // "something happened"
t.getCause();         // null

Try it

Java Message, cause and chaining

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.

Java Stack trace, suppressed and finally

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.

Syntax

Java
public class Throwable implements Serializable
Member Description
Throwable() / Throwable(String message) Creates a throwable with no message or the given message.
Throwable(String message, Throwable cause) Creates a throwable with a message and a cause.
Throwable(Throwable cause) Uses cause.toString() as the message.
String getMessage() The detail message, or null.
String getLocalizedMessage() By default the same as getMessage(); override for localized text.
Throwable getCause() The cause, or null.
Throwable initCause(Throwable cause) Sets the cause once, if it was not set by a constructor.
StackTraceElement[] getStackTrace() The frames captured at creation, innermost first.
void printStackTrace() Prints toString() and the frames (plus causes) to System.err.
void addSuppressed(Throwable) / Throwable[] getSuppressed() Records secondary exceptions (used by try-with-resources).
Throwable fillInStackTrace() Re-captures the current stack. Costly.

Usage notes

  • Message conventions. toString() is the class name, then ": " and the message if there is one. A null message prints only the class name.
  • Always keep the cause. Pass the original exception to the new one's constructor when you translate exceptions, otherwise the real stack trace is lost.
  • Stack traces are expensive to build because the JVM walks the whole stack when the object is created, not when it is thrown. Creating exceptions for ordinary control flow is slow.
  • Do not catch Throwable unless you are a framework boundary, because that also catches Error subclasses such as OutOfMemoryError.
  • Checked or unchecked is decided by the class hierarchy: Throwable and Exception (but not RuntimeException) are checked; Error and RuntimeException are unchecked.
  • Immutable after construction, apart from the cause, suppressed list and stack trace; avoid mutable state in custom subclasses because exceptions cross threads.
  • Serialization: Throwable is Serializable, so custom fields should be serializable too.