wezterm/wezterm · error

no compatible adapter found. Available:\n{}

Error message

no compatible adapter found. Available:\n{}

What it means

With front_end = 'WebGpu', wezterm asks wgpu for an adapter compatible with the window surface across the enabled backends (Vulkan/Metal/DX12/GL). After user webgpu_adapter_preferences filtering (which may reject every adapter) and a default wgpu request_adapter pass, a still-nil adapter raises this error; the message embeds the compatibility list of every adapter wgpu could enumerate, which is the key diagnostic - it shows what the system actually exposes.

Source

Thrown at wezterm-gui/src/termwindow/webgpu.rs:309

            adapter = Some(
                instance
                    .request_adapter(&wgpu::RequestAdapterOptions {
                        power_preference: match config.webgpu_power_preference {
                            WebGpuPowerPreference::HighPerformance => {
                                wgpu::PowerPreference::HighPerformance
                            }
                            WebGpuPowerPreference::LowPower => wgpu::PowerPreference::LowPower,
                        },
                        compatible_surface: Some(&surface),
                        force_fallback_adapter: config.webgpu_force_fallback_adapter,
                    })
                    .await?,
            );
        }

        let adapter = adapter.ok_or_else(|| {
            let adapters = compute_compatibility_list(&instance, backends, &surface);
            anyhow!(
                "no compatible adapter found. Available:\n{}",
                adapters.join("\n")
            )
        })?;

        let adapter_info = adapter.get_info();
        log::trace!("Using adapter: {adapter_info:?}");
        let caps = surface.get_capabilities(&adapter);
        log::trace!("caps: {caps:?}");
        let downlevel_caps = adapter.get_downlevel_capabilities();
        log::trace!("downlevel_caps: {downlevel_caps:?}");

        let (device, queue) = adapter
            .request_device(&wgpu::DeviceDescriptor {
                required_features: wgpu::Features::empty(),
                // WebGL doesn't support all of wgpu's features, so if
                // we're building for the web we'll have to disable some.
                required_limits: if cfg!(target_arch = "wasm32") {

View on GitHub (pinned to 3ff7522b96)

Solutions

1. Unblock immediately: set config.front_end = 'OpenGL'
2. Install Vulkan support on Linux: libvulkan1 + mesa-vulkan-drivers (or the vendor driver); verify with vulkaninfo
3. On WSL: update the Windows GPU driver and confirm /usr/lib/wsl/lib contains libd3d12.so and the vulkan libs
4. Remove or relax webgpu_adapter_preferences; double-check webgpu_force_fallback_adapter
5. Read the adapter list in the error text - it tells you exactly what wgpu can see

Example fix

-- before
config.front_end = 'WebGpu'

-- after
config.front_end = 'OpenGL'

-- Lua config: never depend on a WebGpu adapter being present
config.front_end = 'OpenGL' -- or omit front_end to use the default software-resilient path

When it happens

Trigger: Linux missing Vulkan ICDs/loader (no mesa-vulkan-drivers or vendor driver); remote X11/VNC sessions without DRI; WSL without GPU paravirtualization (missing /usr/lib/wsl d3d12/vulkan libs); a webgpu_adapter_preferences entry matching nothing on this machine; force_fallback_adapter requested but unavailable.

Common situations: Fresh installs, containers, VMs, X-forwarding, WSL1/old WSL GPU setups, or a config carrying adapter preferences copied from different hardware.

Related errors

• texture dimensions {width}x{height} exceeed the max dimensio
• invalid keycode {}: {:#}, {:#}
• {}
• cannot register module {} as package.loaded.{} is already se
• cannot register module wezterm.{name} as it is already set t

AI-assisted analysis of wezterm/wezterm@3ff7522b96 (2026-08-20). Data as JSON: /api/errors/c42d84e62b47bc8d. Report an issue: GitHub.