gfx-rs/wgpu · error

Pointer to X-Server is not set.

Error message

Pointer to X-Server is not set.

What it means

Panic in the Vulkan instance's create_surface: the X11 raw display handle's connection pointer is NULL, so an Xlib/XCB surface cannot be created. The faulty input is the unset X-Server connection in the display handle.

Source

Thrown at wgpu-hal/src/vulkan/instance.rs:1081

    unsafe fn create_surface(
        &self,
        display_handle: raw_window_handle::RawDisplayHandle,
        window_handle: raw_window_handle::RawWindowHandle,
    ) -> Result<super::Surface, crate::InstanceError> {
        use raw_window_handle::{RawDisplayHandle as Rdh, RawWindowHandle as Rwh};

        // TODO: Replace with ash-window, which also lazy-loads the extension based on handle type

        match (window_handle, display_handle) {
            (Rwh::Wayland(handle), Rdh::Wayland(display)) => {
                self.create_surface_from_wayland(display.display.as_ptr(), handle.surface.as_ptr())
            }
            (Rwh::Xlib(handle), Rdh::Xlib(display)) => {
                let display = display.display.expect("Display pointer is not set.");
                self.create_surface_from_xlib(display.as_ptr(), handle.window)
            }
            (Rwh::Xcb(handle), Rdh::Xcb(display)) => {
                let connection = display.connection.expect("Pointer to X-Server is not set.");
                self.create_surface_from_xcb(connection.as_ptr(), handle.window.get())
            }
            #[cfg(drm)]
            (Rwh::Drm(handle), Rdh::Drm(display)) => {
                self.create_surface_from_drm_plane(display.fd, handle.plane)
            }
            (Rwh::AndroidNdk(handle), _) => {
                self.create_surface_android(handle.a_native_window.as_ptr())
            }
            #[cfg(target_env = "ohos")]
            (Rwh::OhosNdk(handle), _) => self.create_surface_ohos(handle.native_window.as_ptr()),
            (Rwh::Win32(handle), _) => {
                let hinstance = handle.hinstance.ok_or_else(|| {
                    crate::InstanceError::new(String::from(
                        "Vulkan requires raw-window-handle's Win32::hinstance to be set",
                    ))
                })?;
                self.create_surface_from_hwnd(hinstance.get(), handle.hwnd.get())

View on GitHub (pinned to 3e11ff59bf)

Solutions

1. Ensure the X11 connection is established and passed as a non-null pointer in the display handle
2. Create the surface through a windowing library that fills the handle correctly

When it happens

Trigger: Thrown at wgpu-hal/src/vulkan/instance.rs:1081 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gfx-rs/wgpu@3e11ff59bf (2026-09-03). Data as JSON: /api/errors/d3dc3c6da05235f0. Report an issue: GitHub.