gfx-rs/wgpu · error

Implementation did not provide a DisplayHandle

Error message

Implementation did not provide a DisplayHandle

What it means

Panic while constructing the wgpu-core Instance's hal descriptor: the raw display handle that must accompany surface creation was absent (DisplayHandle::empty / None), so the backend has no display to register. The faulty input is the missing display handle from the windowing integration.

Source

Thrown at wgpu-core/src/instance.rs:185

        if !instance_desc.backends.contains(A::VARIANT.into()) {
            log::trace!("Instance::new: backend {:?} not requested", A::VARIANT);
            return;
        }

        // If this was Some, it was moved into self
        assert!(instance_desc.display.is_none());

        let hal_desc = hal::InstanceDescriptor {
            name: "wgpu",
            flags: self.flags,
            memory_budget_thresholds: instance_desc.memory_budget_thresholds,
            backend_options: instance_desc.backend_options.clone(),
            telemetry,
            // Pass a borrow, the core instance here keeps the owned handle alive already
            // WARNING: Using self here, not instance_desc!
            display: self.display.as_ref().map(|hdh| {
                hdh.display_handle()
                    .expect("Implementation did not provide a DisplayHandle")
            }),
        };

        use hal::Instance as _;
        // SAFETY: ???
        match unsafe { A::Instance::init(&hal_desc) } {
            Ok(instance) => {
                log::debug!("Instance::new: created {:?} backend", A::VARIANT);
                self.instance_per_backend
                    .push((A::VARIANT, Box::new(instance)));
            }
            Err(err) => {
                log::debug!(
                    "Instance::new: failed to create {:?} backend: {:?}",
                    A::VARIANT,
                    err
                );
            }

View on GitHub (pinned to 3e11ff59bf)

Solutions

1. Provide a valid raw display handle from the windowing system when creating surfaces
2. Ensure the display handle is set before Instance::create_surface is exercised

When it happens

Trigger: Thrown at wgpu-core/src/instance.rs:185 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gfx-rs/wgpu@3e11ff59bf (2026-09-03). Data as JSON: /api/errors/89eb4ca11297b55f. Report an issue: GitHub.