zed-industries/zed · error

Failed to get window handle: {e}

Error message

Failed to get window handle: {e}

What it means

Raised in `WgpuRenderer::new` (native only) when `window.window_handle()` / HasWindowHandle fails, so a raw window handle cannot be obtained to create the wgpu surface. Fires when the window is already closed/destroyed or the platform cannot vend a handle for the window type.

Source

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

    /// multiple windows. The first window to create a renderer will initialize the
    /// context; subsequent windows will share it.
    ///
    /// # Safety
    /// The caller must ensure that the window handle remains valid for the lifetime
    /// of the returned renderer.
    #[cfg(not(target_family = "wasm"))]
    pub fn new<W>(
        gpu_context: GpuContext,
        window: &W,
        config: WgpuSurfaceConfig,
        compositor_gpu: Option<CompositorGpuHint>,
    ) -> anyhow::Result<Self>
    where
        W: HasWindowHandle + HasDisplayHandle + std::fmt::Debug + Send + Sync + Clone + 'static,
    {
        let window_handle = window
            .window_handle()
            .map_err(|e| anyhow::anyhow!("Failed to get window handle: {e}"))?;

        let target = wgpu::SurfaceTargetUnsafe::RawHandle {
            // Fall back to the display handle already provided via InstanceDescriptor::display.
            raw_display_handle: None,
            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

View on GitHub (pinned to f4178619ac)

Solutions

1. Create the renderer while the window is still alive and visible; do not defer past window destruction.
2. Ensure the window type correctly implements HasWindowHandle/HasDisplayHandle.
3. On Wayland/X11, verify the compositor connection is still valid.
4. Handle the error by surfacing a 'cannot initialize GPU' message to the user.

When it happens

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