{"record":{"id":"c42d84e62b47bc8d","repo":"wezterm/wezterm","slug":"no-compatible-adapter-found-available-n","errorCode":null,"errorMessage":"no compatible adapter found. Available:\\n{}","messagePattern":"no compatible adapter found\\. Available:\\\\n(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"wezterm-gui/src/termwindow/webgpu.rs","lineNumber":309,"sourceCode":"            adapter = Some(\n                instance\n                    .request_adapter(&wgpu::RequestAdapterOptions {\n                        power_preference: match config.webgpu_power_preference {\n                            WebGpuPowerPreference::HighPerformance => {\n                                wgpu::PowerPreference::HighPerformance\n                            }\n                            WebGpuPowerPreference::LowPower => wgpu::PowerPreference::LowPower,\n                        },\n                        compatible_surface: Some(&surface),\n                        force_fallback_adapter: config.webgpu_force_fallback_adapter,\n                    })\n                    .await?,\n            );\n        }\n\n        let adapter = adapter.ok_or_else(|| {\n            let adapters = compute_compatibility_list(&instance, backends, &surface);\n            anyhow!(\n                \"no compatible adapter found. Available:\\n{}\",\n                adapters.join(\"\\n\")\n            )\n        })?;\n\n        let adapter_info = adapter.get_info();\n        log::trace!(\"Using adapter: {adapter_info:?}\");\n        let caps = surface.get_capabilities(&adapter);\n        log::trace!(\"caps: {caps:?}\");\n        let downlevel_caps = adapter.get_downlevel_capabilities();\n        log::trace!(\"downlevel_caps: {downlevel_caps:?}\");\n\n        let (device, queue) = adapter\n            .request_device(&wgpu::DeviceDescriptor {\n                required_features: wgpu::Features::empty(),\n                // WebGL doesn't support all of wgpu's features, so if\n                // we're building for the web we'll have to disable some.\n                required_limits: if cfg!(target_arch = \"wasm32\") {","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/wezterm/wezterm/blob/3ff7522b9617ec920f7fbdb22b57e93d42d93ee9/wezterm-gui/src/termwindow/webgpu.rs#L291-L327","documentation":"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.","triggerScenarios":"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.","commonSituations":"Fresh installs, containers, VMs, X-forwarding, WSL1/old WSL GPU setups, or a config carrying adapter preferences copied from different hardware.","solutions":["Unblock immediately: set config.front_end = 'OpenGL'","Install Vulkan support on Linux: libvulkan1 + mesa-vulkan-drivers (or the vendor driver); verify with vulkaninfo","On WSL: update the Windows GPU driver and confirm /usr/lib/wsl/lib contains libd3d12.so and the vulkan libs","Remove or relax webgpu_adapter_preferences; double-check webgpu_force_fallback_adapter","Read the adapter list in the error text - it tells you exactly what wgpu can see"],"exampleFix":"-- before\nconfig.front_end = 'WebGpu'\n\n-- after\nconfig.front_end = 'OpenGL'","handlingStrategy":"fallback","validationCode":"-- Lua config: never depend on a WebGpu adapter being present\nconfig.front_end = 'OpenGL' -- or omit front_end to use the default software-resilient path","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Verify GPU availability (vulkaninfo, WSL gpu libs) before choosing WebGpu","Ship configs without hardcoded webgpu_adapter_preferences across machines","Keep an OpenGL front_end fallback documented for containers, VMs and remote sessions"],"tags":["wezterm","webgpu","gpu","vulkan","front-end","config"],"backgroundTag":"no-compatible-gpu-adapter","analyzedSha":"3ff7522b9617ec920f7fbdb22b57e93d42d93ee9","analyzedAt":"2026-08-20T04:47:31.434Z","contentChangedAt":"2026-08-20T04:47:31.434Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}