gfx-rs/wgpu · error

Failed to get EGL 1.5 for surfaceless

Error message

Failed to get EGL 1.5 for surfaceless

What it means

Panic in GLES Instance::init: creating an EGL display for the surfaceless (EGL_MESA_platform_surfaceless) platform requires EGL 1.5, but the loaded EGL does not provide it, so initialization of that path cannot continue.

Source

Thrown at wgpu-hal/src/gles/egl.rs:880

                        xcb_display_handle
                            .connection
                            .map_or(khronos_egl::DEFAULT_DISPLAY, ptr::NonNull::as_ptr),
                        &display_attributes,
                    )
                }
                .map_err(instance_err("failed to get XCB display"))?;
                (display, WindowKind::X11)
            }
            x if client_ext_str.contains("EGL_MESA_platform_surfaceless") => {
                log::debug!(
                    "No (or unknown) windowing system ({x:?}) present. Using surfaceless platform"
                );
                #[allow(
                    clippy::unnecessary_literal_unwrap,
                    reason = "this is only a literal on Emscripten"
                )]
                // TODO: This extension is also supported on EGL 1.4 with EGL_EXT_platform_base: https://registry.khronos.org/EGL/extensions/MESA/EGL_MESA_platform_surfaceless.txt
                let egl = egl1_5.expect("Failed to get EGL 1.5 for surfaceless");
                let display = unsafe {
                    egl.get_platform_display(
                        EGL_PLATFORM_SURFACELESS_MESA,
                        khronos_egl::DEFAULT_DISPLAY,
                        &[khronos_egl::ATTRIB_NONE],
                    )
                }
                .map_err(instance_err("failed to get MESA surfaceless display"))?;
                (display, WindowKind::Unknown)
            }
            x => {
                log::debug!(
                    "No (or unknown) windowing system {x:?} and EGL_MESA_platform_surfaceless not available. Using default platform"
                );
                let display =
                    unsafe { egl.get_display(khronos_egl::DEFAULT_DISPLAY) }.ok_or_else(|| {
                        crate::InstanceError::new("Failed to get default display".into())
                    })?;

View on GitHub (pinned to 3e11ff59bf)

Solutions

1. Provide a real display server connection (X11/Wayland) instead of surfaceless
2. Upgrade the EGL implementation to 1.5 for surfaceless operation

When it happens

Trigger: Thrown at wgpu-hal/src/gles/egl.rs:880 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/f053c22432fc353a. Report an issue: GitHub.