{"record":{"id":"eca9ada890548917","repo":"gfx-rs/wgpu","slug":"expected-valid-handle-for-canvas","errorCode":null,"errorMessage":"expected valid handle for canvas","messagePattern":"expected valid handle for canvas","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"wgpu/src/backend/webgpu.rs","lineNumber":1702,"sourceCode":"                            .expect(\"expected to find single canvas\")\n                            .into();\n                        canvas_node.into()\n                    }\n                    raw_window_handle::RawWindowHandle::WebCanvas(handle) => {\n                        let value: &JsValue = unsafe { handle.obj.cast().as_ref() };\n                        value.clone().unchecked_into()\n                    }\n                    raw_window_handle::RawWindowHandle::WebOffscreenCanvas(handle) => {\n                        let value: &JsValue = unsafe { handle.obj.cast().as_ref() };\n                        let canvas: web_sys::OffscreenCanvas = value.clone().unchecked_into();\n                        let context_result = canvas.get_context(\"webgpu\");\n\n                        return self.create_surface_from_context(\n                            Canvas::Offscreen(canvas),\n                            context_result,\n                        );\n                    }\n                    _ => panic!(\"expected valid handle for canvas\"),\n                };\n\n                let context_result = canvas_element.get_context(\"webgpu\");\n                self.create_surface_from_context(Canvas::Canvas(canvas_element), context_result)\n            }\n        }\n    }\n\n    fn request_adapter(\n        &self,\n        options: &crate::RequestAdapterOptions<'_, '_>,\n    ) -> Pin<Box<dyn dispatch::RequestAdapterFuture>> {\n        let requested_backends = self.requested_backends;\n\n        //TODO: support this check, return `None` if the flag is not set.\n        // It's not trivial, since we need the Future logic to have this check,\n        // and currently the Future here has no room for extra parameter `backends`.\n        if !(requested_backends.contains(wgt::Backends::BROWSER_WEBGPU)) {","sourceCodeStart":1684,"sourceCodeEnd":1720,"githubUrl":"https://github.com/gfx-rs/wgpu/blob/3e11ff59bf3f9795d285ecc045014089640d7248/wgpu/src/backend/webgpu.rs#L1684-L1720","documentation":"create_surface on the web backend panics when the raw window/canvas handle passed to it is not one of the recognized web surface targets (an HTMLCanvasElement or OffscreenCanvas). The 'Params' hit in benches is unrelated code; the actual condition is that SurfaceTargetRaw or the converted handle did not match any supported web canvas variant.","triggerScenarios":"Calling instance.create_surface with a raw handle whose downcast to a web canvas type fails, e.g. passing a native window handle (Window, VkSurfaceKHR, etc.) to a wasm32-web build, or a corrupted/unexpected SurfaceTargetRaw enum value.","commonSituations":"Shared cross-platform code passing native window handles on web; using RawWindowHandle from a non-DOM source; mixing wgpu versions where SurfaceTarget variants changed.","solutions":["On web, create surfaces from an HTMLCanvasElement or OffscreenCanvas (or pass the canvas via raw handle tagged as web canvas) rather than native window handles.","Use a raw-window-handle web variant (WebCanvas/WebDisplayHandle) that carries the DOM canvas id.","Gate surface creation code per-platform so native handles never reach the wasm build."],"exampleFix":"// before\nlet surface = instance.create_surface(native_window).unwrap(); // wasm32: panics\n// after (web)\nlet surface = instance.create_surface(wgpu::SurfaceTarget::Canvas(canvas_element)).unwrap();","handlingStrategy":"validation","validationCode":"// only pass DOM canvases as surface targets on wasm\nassert!(cfg!(target_arch = \"wasm32\") == canvas_is_web_target, \"native window handles cannot create surfaces on web\");","typeGuard":"fn is_valid_web_surface_target(t: &wgpu::SurfaceTargetRaw) -> bool {\n    matches!(t, wgpu::SurfaceTargetRaw::WebCanvas(_) | wgpu::SurfaceTargetRaw::WebOffscreenCanvas(_))\n}","tryCatchPattern":null,"preventionTips":["On web, always create surfaces from HTMLCanvasElement/OffscreenCanvas or raw-window-handle WebCanvas/WebDisplayHandle.","Keep native handle-based surface creation behind cfg(not(target_arch = \"wasm32\")).","Pin consistent wgpu versions so SurfaceTarget variants match across the workspace."],"tags":["webgpu","wasm","surface","canvas"],"backgroundTag":"invalid-surface-target","analyzedSha":"3e11ff59bf3f9795d285ecc045014089640d7248","analyzedAt":"2026-09-03T01:43:21.459Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T07:17:11.731Z"}