{"record":{"id":"f880b308ba5eaad0","repo":"gfx-rs/wgpu","slug":"wgpu-error-err","errorCode":null,"errorMessage":"wgpu error: {err}\n","messagePattern":"wgpu error: (.+?)\n","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"wgpu-core/src/error.rs","lineNumber":193,"sourceCode":"                } else {\n                    // direct call preserves #[track_caller] where dyn can't\n                    default_error_handler(err)\n                }\n            }\n        }\n    }\n}\n\nimpl fmt::Debug for InternalErrorSink {\n    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {\n        write!(f, \"ErrorSink\")\n    }\n}\n\n#[track_caller]\nfn default_error_handler(err: Error) -> ! {\n    log::error!(\"Handling wgpu errors as fatal by default\");\n    panic!(\"wgpu error: {err}\\n\");\n}\n\n#[derive(Debug, Error)]\n#[error(\"Error scope stack is empty\")]\npub struct EmptyErrorScopeStack;\n\nimpl Device {\n    pub fn on_uncaptured_error(&self, handler: Arc<dyn UncapturedErrorHandler>) {\n        let mut error_sink = self.error_sink.0.lock();\n        error_sink.uncaptured_handler = Some(handler);\n    }\n\n    /// <https://gpuweb.github.io/gpuweb/#dom-gpudevice-pusherrorscope>\n    pub fn push_error_scope(&self, filter: ErrorFilter) {\n        let mut error_sink = self.error_sink.0.lock();\n        let thread_id = thread_id::ThreadId::current();\n        let scopes = error_sink.scopes.entry(thread_id).or_default();\n        scopes.push(ErrorScope {","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/gfx-rs/wgpu/blob/3e11ff59bf3f9795d285ecc045014089640d7248/wgpu-core/src/error.rs#L175-L211","documentation":"This is wgpu's default global error handler. When a WebGPU validation or out-of-memory error occurs and the application has not installed its own error handler via `Device::set_uncaptured_error_handler`, wgpu logs the error and panics with 'wgpu error: {err}'. It means a wgpu API call failed validation (or the device errored) and the error was not captured by any error scope.","triggerScenarios":"Any wgpu call that produces a device error without an enclosing push_error_scope/pop_error_scope and without a custom uncaptured-error handler: e.g. creating a buffer larger than device limits, using a texture with wrong usage flags, submitting a command encoder with invalid passes, mapping a buffer twice, or device loss.","commonSituations":"Early development when resource limits (max_buffer_size, max_texture_dimension) are exceeded; forgetting push_error_scope around risky calls; running code on a device that was lost; API misuse that validation rejects (bad bind group layout matches).","solutions":["Install an uncaptured error handler with device.set_uncaptured_error_handler(|err| ...) to log instead of panic.","Wrap risky operations in device.push_error_scope(...)/pop_error_scope(...).await and inspect the returned error.","Fix the underlying validation problem: check limits, usage flags, and bind group compatibility against device.limits()/features.","In panic hooks or catching_unwind, treat this panic as fatal-by-design; wgpu errors must be handled, not caught.","Read the full panic message: the inner Error (e.g. CreateBufferError) names the exact violated rule."],"exampleFix":"// before\nlet buf = device.create_buffer(&desc); // panics on validation failure\n// after\ndevice.set_uncaptured_error_handler(|err| log::error!(\"wgpu error: {err}\"));\nlet buf = device.create_buffer(&desc);","handlingStrategy":"try-catch","validationCode":"let handler = device.poll(...); // ensure device limits checked before resource creation\nif desc.size > device.limits().max_buffer_size {\n    return Err(\"buffer too large\");\n}","typeGuard":null,"tryCatchPattern":"device.set_uncaptured_error_handler(|err| {\n    log::error!(\"wgpu error: {err}\");\n    // route to telemetry instead of panicking\n});","preventionTips":["Always install set_uncaptured_error_handler early in app startup.","Use push_error_scope/pop_error_scope around batched risky operations.","Check device.limits() and device.features() before creating resources.","Log the inner error type (CreateBufferError etc.) to pinpoint the violated rule."],"tags":["wgpu","panic","validation-error","error-scope"],"backgroundTag":"uncaptured-wgpu-error","analyzedSha":"3e11ff59bf3f9795d285ecc045014089640d7248","analyzedAt":"2026-09-03T01:43:21.459Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T07:17:11.731Z"}