{"record":{"id":"531ae4d0fa208d63","repo":"kovidgoyal/kitty","slug":"failed-to-load-glfwgetx11display","errorCode":null,"errorMessage":"Failed to load glfwGetX11Display","messagePattern":"Failed to load glfwGetX11Display","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kitty/glfw.c","lineNumber":2996,"sourceCode":"        PyTuple_SET_ITEM(result, i, x);\n    }\n    return Py_NewRef(result);\n}\n\n\nstatic PyObject *\nprimary_monitor_content_scale(PYNOARG) {\n    GLFWmonitor *monitor = glfwGetPrimaryMonitor();\n    float xscale = 1.0, yscale = 1.0;\n    if (monitor) glfwGetMonitorContentScale(monitor, &xscale, &yscale);\n    return Py_BuildValue(\"ff\", xscale, yscale);\n}\n\nstatic PyObject *\nx11_display(PYNOARG) {\n    if (glfwGetX11Display) {\n        return PyLong_FromVoidPtr(glfwGetX11Display());\n    } else log_error(\"Failed to load glfwGetX11Display\");\n    Py_RETURN_NONE;\n}\n\nstatic PyObject *\nwayland_compositor_data(PYNOARG) {\n    pid_t pid = -1;\n    const char *missing_capabilities = NULL;\n    if (global_state.is_wayland && glfwWaylandCompositorPID) {\n        pid = glfwWaylandCompositorPID();\n        missing_capabilities = glfwWaylandMissingCapabilities();\n    }\n    return Py_BuildValue(\"Ls\", (long long)pid, missing_capabilities);\n}\n\nstatic PyObject *\nx11_window_id(PyObject UNUSED *self, PyObject *os_wid) {\n    OSWindow *w = os_window_for_id(PyLong_AsUnsignedLongLong(os_wid));\n    if (!w) {","sourceCodeStart":2978,"sourceCodeEnd":3014,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/glfw.c#L2978-L3014","documentation":"kitty's x11_display() Python binding tried to use glfwGetX11Display but the function pointer is NULL — meaning GLFW was not built with X11 support or the current session is not X11 (e.g. running under Wayland). The function pointer is resolved at load time; NULL means the X11 code path is unavailable, so Py_None is returned instead of the Display pointer.","triggerScenarios":"Calling kitty's x11_display() Python/C API (used by window management helpers like gl_x11_window / x11 display queries) while running under Wayland, or with a GLFW build compiled without X11 backends.","commonSituations":"Running kitty on Wayland ($XDG_SESSION_TYPE=wayland) and scripts/kittens that assume X11; custom kitty builds with GLFW X11 support disabled; SSH into a headless box.","solutions":["Verify the session type: echo $XDG_SESSION_TYPE — if wayland, use Wayland equivalents (wayland_compositor_data) instead of x11_display()","If X11 is required, run kitty under XWayland/X11: env GLFW_PLATFORM=x11 kitty or launch from an X11 session","Rebuild kitty/glfw with X11 support if it was disabled at compile time"],"exampleFix":"# before\nimport kitty.fast_data_types as fdt\ndisplay = fdt.x11_display()\n# after\nimport os\nif os.environ.get('XDG_SESSION_TYPE') == 'x11':\n    display = fdt.x11_display()\nelse:\n    display = None  # use wayland APIs instead","handlingStrategy":"type-guard","validationCode":"import os\n\ndef get_x11_display():\n    if os.environ.get('XDG_SESSION_TYPE') != 'x11':\n        return None\n    import kitty.fast_data_types as fdt\n    return fdt.x11_display()  # may still be None if built without X11","typeGuard":"def has_x11() -> bool:\n    return os.environ.get('XDG_SESSION_TYPE') == 'x11' and os.environ.get('DISPLAY') is not None","tryCatchPattern":null,"preventionTips":["Branch on XDG_SESSION_TYPE/DISPLAY before calling X11-specific bindings","Use the Wayland equivalents (wayland_compositor_data) when on Wayland","Note the function returns Py_None, not an exception — check for None explicitly"],"tags":["kitty","x11","wayland","glfw","display","platform-mismatch"],"backgroundTag":"x11-display-unavailable","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}