Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Java

Throwable.getMessage(): read an exception’s detail message

Read the message from a specific exception, handle a missing message, and distinguish the primary exception from its causes and suppressed exceptions.

Version: Java SE 21

Syntax

public String getMessage()

Throwable.getMessage() is a no-argument instance method. The call e.getMessage() returns the detail message of the object e as a String, or null. A null result is not the empty string "". Check the result before using it as a string. Calling the method on a null reference e itself throws NullPointerException.

new NullPointerException("name").getMessage() returns "name". Without an explicit non-null message, the result can be implementation-specific or null; Java SE 21 does not guarantee exact wording or that a variable name appears. A caught IllegalArgumentException inherits getMessage() and can return the text supplied to its constructor.

getCause() returns the cause object, or null when the cause is absent or unknown. For an acyclic chain, follow getCause() until it returns null, calling getMessage() on each cause. IllegalArgumentException(String, Throwable) does not append the cause’s message to the supplied text. The IllegalArgumentException(Throwable) overload derives its message from cause.toString(), or uses null when the cause is null.

If the body of a try-with-resources statement and close() throw distinct exceptions, the body’s exception remains primary. With suppression enabled, the closing exception goes into the array returned by getSuppressed(), not into the cause chain. Read the message from each element separately; the array is empty if nothing was suppressed or suppression is disabled.

getMessage() does not return a stack trace or automatically add the class name. By default, getLocalizedMessage() returns the same result as getMessage(), but a subclass can override it. Treat message text as diagnostic information, not an error code: do not branch on it or expose unreviewed internal messages to users.

Examples

public class Main {
    static final class Resource implements AutoCloseable {
        @Override
        public void close() {
            throw new IllegalStateException("close fail");
        }
    }

    public static void main(String[] args) {
        try (Resource resource = new Resource()) {
            throw new IllegalArgumentException("primary", new NullPointerException("name"));
        } catch (IllegalArgumentException e) {
            System.out.println("Caught: " + e.getMessage());
            for (Throwable cause = e.getCause(); cause != null; cause = cause.getCause()) {
                System.out.println("Cause: " + cause.getMessage());
            }
            for (Throwable suppressed : e.getSuppressed()) {
                System.out.println("Suppressed: " + suppressed.getMessage());
            }
        }

        String message = new IllegalArgumentException().getMessage();
        System.out.println("No message: " + (message == null ? "(absent)" : message));
    }
}

Result

Caught: primary
Cause: name
Suppressed: close fail
No message: (absent)

The output separates the caught `IllegalArgumentException` message (`primary`), its cause’s message (`name`), and the suppressed `close()` exception’s message (`close fail`). In the last line, the program substitutes `(absent)` for `null`.

Related lessons

  • Java · Lesson 28 · Intermediate · Version: 2
  • Java · Lesson 29 · Intermediate · Version: 2
  • Java · Lesson 30 · Intermediate · Version: 2
  • Java · Lesson 31 · Intermediate · Version: 2

Sources