{"record":{"id":"c3df4702090af152","repo":"java-native-access/jna","slug":"keyboardutils-requires-a-keyboard","errorCode":null,"errorMessage":"KeyboardUtils requires a keyboard","messagePattern":"KeyboardUtils requires a keyboard","errorType":"exception","errorClass":"HeadlessException","httpStatus":null,"severity":"error","filePath":"contrib/platform/src/com/sun/jna/platform/KeyboardUtils.java","lineNumber":49,"sourceCode":"import com.sun.jna.platform.unix.X11;\nimport com.sun.jna.platform.unix.X11.Display;\nimport com.sun.jna.platform.win32.User32;\nimport com.sun.jna.platform.win32.WinUser;\n\n/** Provide access to the local keyboard state.  Note that this is meaningless\n * on a headless system and some VNC setups.\n *\n * @author twall\n */\n// TODO: key clicks\n// TODO: auto-repeat\n// TODO: keyboard bell\n// TODO: led state\npublic class KeyboardUtils {\n    static final NativeKeyboardUtils INSTANCE;\n    static {\n        if (GraphicsEnvironment.isHeadless()) {\n            throw new HeadlessException(\"KeyboardUtils requires a keyboard\");\n        }\n        if (Platform.isWindows()) {\n            INSTANCE = new W32KeyboardUtils();\n        }\n        else if (Platform.isMac()) {\n            INSTANCE = new MacKeyboardUtils();\n            throw new UnsupportedOperationException(\"No support (yet) for \"\n                                                    + System.getProperty(\"os.name\"));\n        }\n        else {\n            INSTANCE = new X11KeyboardUtils();\n        }\n    }\n\n    public static boolean isPressed(int keycode, int location) {\n        return INSTANCE.isPressed(keycode, location);\n    }\n    public static boolean isPressed(int keycode) {","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/KeyboardUtils.java#L31-L67","documentation":"KeyboardUtils' static initializer throws HeadlessException if the JVM reports a headless graphics environment, since the keyboard utilities need a real keyboard/display context. Class initialization fails and INSTANCE is never created.","triggerScenarios":"Referencing KeyboardUtils (any static method like isPressed) while running with -Djava.awt.headless=true, or on a machine without display/input devices (servers, containers).","commonSituations":"CI pipelines and headless servers running key-listening code; Docker containers without X11; java.awt.headless explicitly set true in build/test configs.","solutions":["Run with a display available and java.awt.headless=false (use Xvfb on servers)","Guard KeyboardUtils usage with !GraphicsEnvironment.isHeadless() checks","Use a non-GUI input mechanism (e.g. JLine or native console reading) in headless environments"],"exampleFix":"// before\nboolean pressed = KeyboardUtils.isPressed(KeyEvent.VK_SHIFT);\n// after\nif (GraphicsEnvironment.isHeadless()) {\n    throw new IllegalStateException(\"KeyboardUtils requires a non-headless environment\");\n}\nboolean pressed = KeyboardUtils.isPressed(KeyEvent.VK_SHIFT);","handlingStrategy":"validation","validationCode":"if (GraphicsEnvironment.isHeadless()) {\n    throw new IllegalStateException(\"KeyboardUtils requires a display (non-headless JVM)\");\n}","typeGuard":"boolean keyboardUtilsAvailable() {\n    return !GraphicsEnvironment.isHeadless();\n}","tryCatchPattern":"try {\n    KeyboardUtils.isPressed(keycode);\n} catch (HeadlessException | ExceptionInInitializerError e) {\n    logger.warn(\"No keyboard available in this environment\");\n}","preventionTips":["Do not set java.awt.headless=true in apps using KeyboardUtils","Provide a virtual display (Xvfb) on servers/CI","Check isHeadless() before initializing keyboard features"],"tags":["java","headless","keyboard","awt"],"backgroundTag":"unsupported-platform","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"}