zed-industries/zed · critical

surface configuration failed: {e}

Error message

surface configuration failed: {e}

What it means

After creating a device, GPUI pushes a wgpu validation error scope and configures the surface with a 64x64 test SurfaceConfiguration (caps.formats[0], Fifo present mode, caps.alpha_modes[0]). If wgpu records a validation error while configuring, the scope pops Some(e) and the adapter is rejected. It means the driver/device refused the exact format/alpha-mode/usage combination the capabilities advertised.

Source

Thrown at crates/gpui_wgpu/src/wgpu_context.rs:491

            Self::create_device(adapter).await?;
        let error_scope = device.push_error_scope(wgpu::ErrorFilter::Validation);

        let test_config = wgpu::SurfaceConfiguration {
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
            format: caps.formats[0],
            width: 64,
            height: 64,
            present_mode: wgpu::PresentMode::Fifo,
            desired_maximum_frame_latency: 2,
            alpha_mode: caps.alpha_modes[0],
            view_formats: vec![],
        };

        surface.configure(&device, &test_config);

        let error = error_scope.pop().await;
        if let Some(e) = error {
            anyhow::bail!("surface configuration failed: {e}");
        }

        Ok((
            device,
            queue,
            dual_source_blending,
            color_atlas_texture_format,
        ))
    }

    fn select_color_texture_format(adapter: &wgpu::Adapter) -> anyhow::Result<wgpu::TextureFormat> {
        let required_usages = wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST;
        let bgra_features = adapter.get_texture_format_features(wgpu::TextureFormat::Bgra8Unorm);
        let rgba_features = adapter.get_texture_format_features(wgpu::TextureFormat::Rgba8Unorm);
        #[cfg(target_family = "wasm")]
        if adapter.get_info().backend == wgpu::Backend::Gl
            && rgba_features.allowed_usages.contains(required_usages)
        {

View on GitHub (pinned to f4178619ac)

Solutions

1. Update GPU drivers to a version where surface.configure matches get_capabilities
2. Try a different adapter/vendor by removing GPU vendor overrides (or setting one that works)
3. Switch backends via WGPU_BACKEND (e.g. dx12 vs vulkan on Windows, gl vs vulkan on Linux)
4. Restart the app after reconnecting/removing the remote session so capabilities are re-queried on a live surface

let error_scope = device.push_error_scope(wgpu::ErrorFilter::Validation);
surface.configure(&device, &test_config);
if let Some(e) = error_scope.pop().await {
    // treat as 'adapter unusable', continue with next adapter
    log::info!("surface configuration failed: {e}");
    continue;
}

When it happens

Trigger: surface.configure(&device, &test_config) triggering a wgpu::ErrorFilter::Validation error — driver bugs where reported capabilities do not match what configure accepts, formats that lack RENDER_ATTACHMENT support in practice, or alpha modes the compositor rejects.

Common situations: Buggy or mismatched GPU driver stacks (especially on Windows hybrid graphics and older Linux mesa), remote-desktop surfaces whose capabilities drift after connect/disconnect, and adapters that advertise formats they cannot actually configure.

Related errors

• Too many consecutive GPU errors. Last error: {error}
• Adapter {:?} (backend={:?}, device={:#06x}) is not compatibl
• No GPU adapters found
• No GPU adapter found that can configure the display surface
• no compatible surface formats

AI-assisted analysis of zed-industries/zed@f4178619ac (2026-08-20). Data as JSON: /api/errors/2254b168042e1de7. Report an issue: GitHub.