gfx-rs/wgpu · error

Cannot get document

Error message

Cannot get document

What it means

Panic in the GLES/web create_surface: window()/document() returned None while resolving a Web window handle to its canvas element — the DOM is not reachable from this context (e.g. non-document JS environment). The faulty input is the missing window/document.

Source

Thrown at wgpu-hal/src/gles/web.rs:154

                    self.options.clone(),
                )
            }
            .into_iter()
            .collect()
        } else {
            Vec::new()
        }
    }

    unsafe fn create_surface(
        &self,
        _display_handle: raw_window_handle::RawDisplayHandle,
        window_handle: raw_window_handle::RawWindowHandle,
    ) -> Result<Surface, crate::InstanceError> {
        let canvas: web_sys::HtmlCanvasElement = match window_handle {
            raw_window_handle::RawWindowHandle::Web(handle) => web_sys::window()
                .and_then(|win| win.document())
                .expect("Cannot get document")
                .query_selector(&format!("canvas[data-raw-handle=\"{}\"]", handle.id))
                .expect("Cannot query for canvas")
                .expect("Canvas is not found")
                .dyn_into()
                .expect("Failed to downcast to canvas type"),
            raw_window_handle::RawWindowHandle::WebCanvas(handle) => {
                let value: &JsValue = unsafe { handle.obj.cast().as_ref() };
                value.clone().unchecked_into()
            }
            raw_window_handle::RawWindowHandle::WebOffscreenCanvas(handle) => {
                let value: &JsValue = unsafe { handle.obj.cast().as_ref() };
                let canvas: web_sys::OffscreenCanvas = value.clone().unchecked_into();

                return self.create_surface_from_offscreen_canvas(canvas);
            }
            _ => {
                return Err(crate::InstanceError::new(format!(
                    "window handle {window_handle:?} is not a web handle"

View on GitHub (pinned to 3e11ff59bf)

Solutions

1. Run in a document-backed browser environment (not a worker without DOM access)
2. Provide a canvas-based surface creation path instead of a raw window handle

When it happens

Trigger: Thrown at wgpu-hal/src/gles/web.rs:154 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/6a327c272a7e12eb. Report an issue: GitHub.