zed-industries/zed · error

Failed to create browser graphics surface: {error}

Error message

Failed to create browser graphics surface: {error}

What it means

Raised in `WgpuContext::new_web_with_backend` when `instance.create_surface(SurfaceTarget::Canvas)` fails, meaning wgpu could not wrap the browser canvas as a rendering surface (backend mismatch, e.g. requesting WebGPU on a browser without it, or the canvas is not usable). {error} carries the wgpu CreateSurfaceError.

Source

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

            WebBackendPreference::WebGpu => wgpu::Backends::BROWSER_WEBGPU,
            WebBackendPreference::WebGl => wgpu::Backends::GL,
        };
        let descriptor = wgpu::InstanceDescriptor {
            backends,
            flags: wgpu::InstanceFlags::default(),
            backend_options: wgpu::BackendOptions::default(),
            memory_budget_thresholds: wgpu::MemoryBudgetThresholds::default(),
            display: Some(Box::new(WebDisplaySource)),
        };
        let instance = if preference == WebBackendPreference::Auto {
            wgpu::util::new_instance_with_webgpu_detection(descriptor).await
        } else {
            wgpu::Instance::new(descriptor)
        };
        let surface = instance
            .create_surface(wgpu::SurfaceTarget::Canvas(canvas.clone()))
            .map_err(|error| {
                anyhow::anyhow!("Failed to create browser graphics surface: {error}")
            })?;

        let adapter = instance
            .request_adapter(&wgpu::RequestAdapterOptions {
                power_preference: wgpu::PowerPreference::HighPerformance,
                compatible_surface: Some(&surface),
                force_fallback_adapter: false,
            })
            .await
            .map_err(|error| {
                anyhow::anyhow!(
                    "Failed to request a {preference:?} adapter compatible with the canvas: {error}"
                )
            })?;
        let adapter_info = adapter.get_info();
        let backend = match adapter_info.backend {
            wgpu::Backend::BrowserWebGpu => WgpuBackend::BrowserWebGpu,
            wgpu::Backend::Gl => WgpuBackend::Gl,

View on GitHub (pinned to f4178619ac)

Solutions

1. Fall back to the WebGL (Backends::GL) path when WebGPU surface creation fails.
2. Confirm the browser supports WebGPU (Chrome/Edge 113+, or Firefox with WebGPU enabled).
3. Ensure the canvas element is attached to the DOM and not already in use by another context.
4. Inspect the CreateSurfaceError message to distinguish unsupported backend from invalid canvas.

When it happens

Trigger: Thrown at crates/gpui_wgpu/src/wgpu_context.rs:178 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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