{"record":{"id":"119d21342acbb11c","repo":"gfx-rs/wgpu","slug":"unexpected-vulkan-error-err","errorCode":null,"errorMessage":"Unexpected Vulkan error: {_err:?}","messagePattern":"Unexpected Vulkan error: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"wgpu-hal/src/vulkan/mod.rs","lineNumber":1839,"sourceCode":"/// Maps\n///\n/// - VK_ERROR_OUT_OF_HOST_MEMORY\n/// - VK_ERROR_OUT_OF_DEVICE_MEMORY\n/// - VK_PIPELINE_COMPILE_REQUIRED_EXT\n/// - VK_ERROR_INVALID_SHADER_NV\nfn map_pipeline_err(err: vk::Result) -> crate::DeviceError {\n    // We don't use VK_EXT_pipeline_creation_cache_control\n    // VK_PIPELINE_COMPILE_REQUIRED_EXT\n    // We don't use VK_NV_glsl_shader\n    // VK_ERROR_INVALID_SHADER_NV\n    map_host_device_oom_err(err)\n}\n\n/// Returns [`crate::DeviceError::Unexpected`] or panics if the `internal_error_panic`\n/// feature flag is enabled.\nfn get_unexpected_err(_err: vk::Result) -> crate::DeviceError {\n    #[cfg(feature = \"internal_error_panic\")]\n    panic!(\"Unexpected Vulkan error: {_err:?}\");\n\n    #[allow(unreachable_code)]\n    crate::DeviceError::Unexpected\n}\n\n/// Returns [`crate::DeviceError::OutOfMemory`].\nfn get_oom_err(_err: vk::Result) -> crate::DeviceError {\n    crate::DeviceError::OutOfMemory\n}\n\n/// Returns [`crate::DeviceError::Lost`] or panics if the `device_lost_panic`\n/// feature flag is enabled.\nfn get_lost_err() -> crate::DeviceError {\n    #[cfg(feature = \"device_lost_panic\")]\n    panic!(\"Device lost\");\n\n    #[allow(unreachable_code)]\n    crate::DeviceError::Lost","sourceCodeStart":1821,"sourceCodeEnd":1857,"githubUrl":"https://github.com/gfx-rs/wgpu/blob/3e11ff59bf3f9795d285ecc045014089640d7248/wgpu-hal/src/vulkan/mod.rs#L1821-L1857","documentation":"wgpu-hal's Vulkan backend converts unrecognized vk::Result values into `DeviceError::Unexpected`. If the crate is built with the `internal_error_panic` feature flag, this helper instead panics so unexpected Vulkan results fail loudly during development. Normally the caller receives an Unexpected error rather than a panic.","triggerScenarios":"Any Vulkan call in the backend returning an error result that is not explicitly mapped (e.g. not OUT_OF_MEMORY or DEVICE_LOST), routed through `get_unexpected_err` at wgpu-hal/src/vulkan/mod.rs:1839.","commonSituations":"Driver bugs returning exotic VkResult codes; device-loss variants (DEVICE_LOST_EXTENSION etc.); builds with internal_error_panic enabled running the CTS; hardware removal mid-frame.","solutions":["If the panic fired, treat it as a bug: capture the printed VkResult variant and driver/GPU info.","Update GPU drivers; many unexpected results stem from driver quirks.","Rebuild without the `internal_error_panic` feature to receive a graceful DeviceError::Unexpected instead of panicking.","Check for an earlier device-loss event; subsequent calls may return unexpected results after the device died."],"exampleFix":"// before (Cargo.toml)\nwgpu-hal = { version = \"...\", features = [\"internal_error_panic\"] }\n// after\nwgpu-hal = { version = \"...\" }","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"// Narrow DeviceError before deciding recovery\nfn is_recoverable(err: &wgpu::DeviceError) -> bool {\n    matches!(err, wgpu::DeviceError::Lost | wgpu::DeviceError::OutOfMemory)\n}\n// DeviceError::Unexpected means an unmapped VkResult: log and treat as fatal.","tryCatchPattern":"match queue.submit(Some(encoder.finish())) {\n    Ok(()) => {}\n    Err(e) if matches!(*e, wgpu::DeviceError::Lost | wgpu::DeviceError::OutOfMemory) => recreate_device(),\n    Err(e) => log::error!(\"unexpected Vulkan error: {e}\"), // DeviceError::Unexpected\n}","preventionTips":["Avoid building with internal_error_panic outside CI/testing.","Update drivers before reporting unexpected VkResults.","Watch for an earlier device-loss that poisons later calls.","Log the exact VkResult variant when filing a wgpu issue."],"tags":["vulkan","unexpected-result","device-error","panic"],"backgroundTag":"unexpected-vulkan-result","analyzedSha":"3e11ff59bf3f9795d285ecc045014089640d7248","analyzedAt":"2026-09-03T01:43:21.459Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T07:17:11.731Z"}