How to Handle the Headless Exception in Java

The java.awt.HeadlessException is a runtime exception in Java that occurs when code that is dependent on a keyboard, display or mouse is called in an environment that does not support a keyboard, display or mouse.

Since HeadlessException is an unchecked exception, it does not need to be declared in the throws clause of a method or constructor.

What Causes HeadlessException

The HeadlessException is thrown when Java code that depends on a display device, keyboard, or mouse is called in an environment that does not support any of these. This typically occurs in the Java headless mode, which is a system configuration in which the display device, keyboard, or mouse is lacking.

Certain Java AWT components require peripheral devices and will not work in the headless mode. As a rule of thumb, top-level AWT components such as Frame and Button always need an interactive environment. If these components are used in a non-interactive (headless) environment, a HeadlessException is thrown.

HeadlessException Example

Here’s an example of a HeadlessException thrown when using a JFrame object in the Java headless mode:

import javax.swing.JFrame;

public class HeadlessExceptionExample {
    public static void main(String[] args) {
        JFrame frame = new JFrame("test");
        frame.setVisible(true);
    }
}

When the above code is executed in the Java headless mode using the following command line argument:

-Djava.awt.headless=true

The HeadlessException is thrown:

Exception in thread "main" java.awt.HeadlessException
    at java.desktop/java.awt.GraphicsEnvironment.checkHeadless(GraphicsEnvironment.java:165)
    at java.desktop/java.awt.Window.<init>(Window.java:540)
    at java.desktop/java.awt.Frame.<init>(Frame.java:423)
    at java.desktop/javax.swing.JFrame.<init>(JFrame.java:224)
    at HeadlessExceptionExample.main(HeadlessExceptionExample.java:5)

How to Handle HeadlessException

Since certain Java AWT components such as Frame and Button require peripheral devices, they will not work in the Java headless mode. If they are used in the headless mode, a HeadlessException is thrown.

If such components need to be used in an environment that supports peripheral devices, the headless mode can be disabled in order for them to work properly. This can be done, for example, by setting the java.awt.headless command line argument to false:

-Djava.awt.headless=false

If the code containing such components needs to be executed on both types of environments - a headed environment and a headless one, a conditional approach can be used to display the components in the headed environment only. The earlier example can be updated to use the conditional approach:

import java.awt.GraphicsEnvironment;
import javax.swing.JFrame;

public class HeadlessExceptionExample {
    public static void main(String[] args) {
        if (!GraphicsEnvironment.isHeadless()) {
            JFrame frame = new JFrame("test");
            frame.setVisible(true);
        }
        System.out.println("Continuing execution...");
    }
}

In the updated example above, the JFrame component is only used and displayed in a non-headless environment. Running the above code in a headless environment avoids the HeadlessException and produces the correct output as expected:

Continuing execution...

Track, Analyze and Manage Errors With Rollbar

Managing errors and exceptions in your code is challenging. It can make deploying production code an unnerving experience. Being able to track, analyze, and manage errors in real-time can help you to proceed with more confidence. Rollbar automates error monitoring and triaging, making fixing Java errors easier than ever. Sign Up Today!