zed-industries/zed · error

Failed to create surface: {e}

Error message

Failed to create surface: {e}

What it means

Raised in `WgpuRenderer::new` when `instance.create_surface(window_handle)` fails, meaning wgpu rejected the raw window/display handle combination (unsupported platform, handle belonging to a different display, or already-invalid handle). {e} is the wgpu CreateSurfaceError.

Source

Thrown at crates/gpui_wgpu/src/wgpu_renderer.rs:293

            raw_window_handle: window_handle.as_raw(),
        };

        // Use the existing context's instance if available, otherwise create a new one.
        // The surface must be created with the same instance that will be used for
        // adapter selection, otherwise wgpu will panic.
        let instance = gpu_context
            .borrow()
            .as_ref()
            .map(|ctx| ctx.instance.clone())
            .unwrap_or_else(|| WgpuContext::instance(Box::new(window.clone())));

        // Safety: The caller guarantees that the window handle is valid for the
        // lifetime of this renderer. In practice, the RawWindow struct is created
        // from the native window handles and the surface is dropped before the window.
        let surface = unsafe {
            instance
                .create_surface_unsafe(target)
                .map_err(|e| anyhow::anyhow!("Failed to create surface: {e}"))?
        };

        let mut ctx_ref = gpu_context.borrow_mut();
        let context = match ctx_ref.as_mut() {
            Some(context) => {
                context.check_compatible_with_surface(&surface)?;
                context
            }
            None => ctx_ref.insert(WgpuContext::new(instance, &surface, compositor_gpu)?),
        };

        let atlas = Arc::new(WgpuAtlas::from_context(context));

        Self::new_internal(
            Some(Rc::clone(&gpu_context)),
            context,
            surface,
            config,

View on GitHub (pinned to f4178619ac)

Solutions

1. Verify the raw display/window handle pair is valid and matches the platform backend in the instance.
2. Ensure the surface is created from the same instance used for adapter selection (as this code does) to avoid wgpu panics.
3. Recreate the renderer after the window is re-created rather than reusing a stale handle.
4. Check the CreateSurfaceError variant to distinguish unsupported handle from invalid handle.

When it happens

Trigger: Thrown at crates/gpui_wgpu/src/wgpu_renderer.rs:293 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/cf3b960636dec145. Report an issue: GitHub.