java-native-access/jna · error · Error

X Display is null

Error message

X Display is null

What it means

The X.Display(X11.Display) constructor stores the supplied display handle and throws java.lang.Error('X Display is null') if the caller passes null. It guards against using the wrapper without a valid open Xlib display; every method would otherwise crash in native code.

Source

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

         */
        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.
         */
        public void close() {
            x11.XCloseDisplay(x11Display);
        }

        /**
         * Flushes the output buffer / event queue.
         */
        public void flush() {
            x11.XFlush(x11Display);
        }

        /**

View on GitHub (pinned to d036ad9781)

Solutions

1. Check the XOpenDisplay return value for null before constructing X.Display, and handle the connection failure there.
2. Ensure the X environment is valid (DISPLAY set, X server reachable) so the handle is non-null in the first place.
3. If null may occur, avoid constructing the wrapper and use an optional/fallback code path.
4. Treat this Error as a programming error: add an assertion/null check at the call site.

Example fix

// before
X.Display display = new X.Display(x11.XOpenDisplay(null));
// after
X11.Display d = x11.XOpenDisplay(null);
if (d == null) {
    throw new IllegalStateException("Cannot connect to X server (is DISPLAY set?)");
}
X.Display display = new X.Display(d);

X11.Display d = x11.XOpenDisplay(name);
if (d == null) throw new IllegalStateException("XOpenDisplay failed for " + name);

boolean isValidDisplay(X11.Display d) {
    return d != null;
}

try {
    X.Display display = new X.Display(maybeNullDisplay);
} catch (Error e) {
    if ("X Display is null".equals(e.getMessage())) {
        throw new IllegalStateException("Caller passed a null X display handle", e);
    }
    throw e;
}

When it happens

Trigger: Calling new X.Display(x11Display) with null — typically because a previous XOpenDisplay call returned null (its failure was not checked) and the null handle was passed straight through.

Common situations: Passing the result of XOpenDisplay without a null check; chaining constructor calls where an earlier 'Can't open X Display' path produced a null handle.

Related errors

• Can't open X Display
• Can't open X Display
• Cannot get window manager info properties. (_NET_SUPPORTING_
• Cannot get client list properties (_NET_CLIENT_LIST or _WIN_
• errno: {eno}

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