What causes "Can't open X Display" in java-native-access/jna?

Verify DISPLAY is set and correct (echo $DISPLAY, e.g. :0) and that the X server is running.

java-native-access/jna · critical · Error

Can't open X Display

Error message

Can't open X Display

What it means

X.Display's no-arg constructor calls XOpenDisplay(null) to connect to the default X server. If the connection fails, XOpenDisplay returns NULL and the constructor throws java.lang.Error('Can't open X Display'). The library surfaces Xlib connection failure as an Error because the display is fundamental to all subsequent X calls.

Source

Thrown at contrib/x11/src/jnacontrib/x11/api/X.java:99

     */
    public static class Display {
        /**
         * Open display.
         */
        private X11.Display x11Display;
        /**
         * HashMap<String,X11.Atom>.
         */
        private HashMap<String, Atom> atomsHash = new HashMap<String, Atom>();

        /**
         * Creates the OOWindowUtils using the default display.
         */
        public Display() {
            x11Display = x11.XOpenDisplay(null);

            if (x11Display == null) {
                throw new Error("Can't open X Display");
            }
        }

        /**
         * Creates the OOWindowUtils using a given display.
         *
         * @param x11Display open display
         */
        public Display(X11.Display x11Display) {
            this.x11Display = x11Display;

            if (x11Display == null) {
                throw new Error("X Display is null");
            }
        }

        /**
         * Closes the display.

View on GitHub (pinned to d036ad9781)

Solutions

Verify DISPLAY is set and correct (echo $DISPLAY, e.g. :0) and that the X server is running.
Connect with X forwarding: ssh -X user@host, or run an X server (xvfb for headless automation).
Check xauth permissions: run xhost +local: or ensure ~/.Xauthority is valid for the current user.
Catch the Error in code that must run headless and fall back to a non-X implementation.

Example fix

// before
X.Display display = new X.Display();
// after
if (System.getenv("DISPLAY") == null) {
    throw new IllegalStateException("Headless environment: DISPLAY is not set");
}
X.Display display = new X.Display();

Defensive patterns

Strategy: try-catch

Validate before calling

String display = System.getenv("DISPLAY");
boolean xAvailable = display != null && !display.isEmpty();

Try / catch

try {
    X.Display display = new X.Display();
} catch (Error e) {
    if ("Can't open X Display".equals(e.getMessage())) {
        throw new IllegalStateException("No X server available (DISPLAY="
            + System.getenv("DISPLAY") + ")", e);
    }
    throw e;
}

Prevention

Check DISPLAY and X server availability before constructing X.Display.
Use Xvfb or X forwarding in headless/CI environments.
Verify xauth credentials for the current user.
Fall back to a non-X code path when no display exists.

When it happens

Trigger: Constructing new X.Display() when no X server is reachable: DISPLAY is unset/wrong, no X server is running, X11 authorization (xauth) rejects the client, or connecting over SSH without X forwarding.

Common situations: Running on a headless Linux server, cron/systemd service without DISPLAY, SSH session without -X/-Y forwarding, or wrong DISPLAY value (e.g. :1 vs :0).

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of java-native-access/jna@d036ad9781 (2026-09-12). Data as JSON: /api/errors/03bff06466f26d63. Report an issue: GitHub.