{"record":{"id":"101aed27784736ed","repo":"java-native-access/jna","slug":"can-t-open-x-display","errorCode":null,"errorMessage":"Can't open X Display","messagePattern":"Can't open X Display","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"contrib/platform/src/com/sun/jna/platform/KeyboardUtils.java","lineNumber":157,"sourceCode":"                return X11.XK_Control_L;\n            }\n            if (code == KeyEvent.VK_ALT) {\n                if ((location & KeyEvent.KEY_LOCATION_RIGHT) != 0)\n                    return X11.XK_Alt_R;\n                return X11.XK_Alt_L;\n            }\n            if (code == KeyEvent.VK_META) {\n                if ((location & KeyEvent.KEY_LOCATION_RIGHT) != 0)\n                    return X11.XK_Meta_R;\n                return X11.XK_Meta_L;\n            }\n            return 0;\n        }\n        public boolean isPressed(int keycode, int location) {\n            X11 lib = X11.INSTANCE;\n            Display dpy = lib.XOpenDisplay(null);\n            if (dpy == null) {\n                throw new Error(\"Can't open X Display\");\n            }\n            try {\n                byte[] keys = new byte[32];\n                // Ignore the return value\n                lib.XQueryKeymap(dpy, keys);\n                int keysym = toKeySym(keycode, location);\n                for (int code=5;code < 256;code++) {\n                    int idx = code / 8;\n                    int shift = code % 8;\n                    if ((keys[idx] & (1 << shift)) != 0) {\n                        int sym = lib.XKeycodeToKeysym(dpy, (byte)code, 0).intValue();\n                        if (sym == keysym)\n                            return true;\n                    }\n                }\n            }\n            finally {\n                lib.XCloseDisplay(dpy);","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/KeyboardUtils.java#L139-L175","documentation":"X11KeyboardUtils.isPressed throws Error when XOpenDisplay(null) returns null, meaning no X display connection can be established. The native X11 library is required to query the keymap, so without a display the check cannot proceed.","triggerScenarios":"Calling KeyboardUtils.isPressed on an X11 (Linux/Unix) system where the DISPLAY environment variable is unset/invalid, the X server is unreachable, or X authorization (xauth) denies the connection.","commonSituations":"SSH sessions without X forwarding; running inside Docker/systemd services with no DISPLAY; Wayland-only sessions where XOpenDisplay fails.","solutions":["Ensure DISPLAY is set correctly (e.g. export DISPLAY=:0) and the X server accepts connections","Use ssh -X / xhost+ or xauth to grant access when connecting remotely","Run inside an Xvfb virtual display on headless servers; prefer Wayland-native APIs on Wayland"],"exampleFix":"// before\nboolean pressed = KeyboardUtils.isPressed(code);\n// after\nif (System.getenv(\"DISPLAY\") == null) {\n    throw new IllegalStateException(\"DISPLAY not set; cannot query X11 keymap\");\n}\nboolean pressed = KeyboardUtils.isPressed(code);","handlingStrategy":"validation","validationCode":"if (System.getenv(\"DISPLAY\") == null || System.getenv(\"DISPLAY\").isEmpty()) {\n    throw new IllegalStateException(\"DISPLAY not set; X11 keyboard queries unavailable\");\n}","typeGuard":"boolean x11Available() {\n    String d = System.getenv(\"DISPLAY\");\n    return d != null && !d.isEmpty();\n}","tryCatchPattern":"try {\n    pressed = KeyboardUtils.isPressed(keycode);\n} catch (Error e) {\n    logger.warn(\"Cannot open X display: \" + e.getMessage());\n}","preventionTips":["Set DISPLAY and verify with xdpyinfo before running","Use ssh -Y / xauth for remote X access","Start Xvfb in headless/container environments"],"tags":["java","x11","keyboard","display"],"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-14T05:17:10.506Z"}