{"record":{"id":"03bff06466f26d63","repo":"java-native-access/jna","slug":"can-t-open-x-display-03bff0","errorCode":null,"errorMessage":"Can't open X Display","messagePattern":"Can't open X Display","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"contrib/x11/src/jnacontrib/x11/api/X.java","lineNumber":99,"sourceCode":"     */\n    public static class Display {\n        /**\n         * Open display.\n         */\n        private X11.Display x11Display;\n        /**\n         * HashMap<String,X11.Atom>.\n         */\n        private HashMap<String, Atom> atomsHash = new HashMap<String, Atom>();\n\n        /**\n         * Creates the OOWindowUtils using the default display.\n         */\n        public Display() {\n            x11Display = x11.XOpenDisplay(null);\n\n            if (x11Display == null) {\n                throw new Error(\"Can't open X Display\");\n            }\n        }\n\n        /**\n         * Creates the OOWindowUtils using a given display.\n         *\n         * @param x11Display open display\n         */\n        public Display(X11.Display x11Display) {\n            this.x11Display = x11Display;\n\n            if (x11Display == null) {\n                throw new Error(\"X Display is null\");\n            }\n        }\n\n        /**\n         * Closes the display.","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/x11/src/jnacontrib/x11/api/X.java#L81-L117","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"// before\nX.Display display = new X.Display();\n// after\nif (System.getenv(\"DISPLAY\") == null) {\n    throw new IllegalStateException(\"Headless environment: DISPLAY is not set\");\n}\nX.Display display = new X.Display();","handlingStrategy":"try-catch","validationCode":"String display = System.getenv(\"DISPLAY\");\nboolean xAvailable = display != null && !display.isEmpty();","typeGuard":null,"tryCatchPattern":"try {\n    X.Display display = new X.Display();\n} catch (Error e) {\n    if (\"Can't open X Display\".equals(e.getMessage())) {\n        throw new IllegalStateException(\"No X server available (DISPLAY=\"\n            + System.getenv(\"DISPLAY\") + \")\", e);\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["x11","linux","display","headless"],"backgroundTag":"missing-env-var","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}