{"record":{"id":"f1217ecac93e022e","repo":"bevyengine/bevy","slug":"failed-to-process-shader-0","errorCode":null,"errorMessage":"Failed to process shader:\n{0}","messagePattern":"Failed to process shader:\n(.+?)","errorType":"exception","errorClass":"ShaderCacheError","httpStatus":null,"severity":"error","filePath":"crates/bevy_shader/src/shader_cache.rs","lineNumber":542,"sourceCode":"    }\n\n    fn display_name(&self, module_path: &wesl::syntax::ModulePath) -> Option<String> {\n        let module_path = self.canonical_path(module_path);\n        let asset_id = self.module_path_to_asset_id.get(&module_path)?;\n        let shader = self.shaders.get(asset_id)?;\n        Some(shader.path.clone())\n    }\n}\n\n/// Type of error returned by a `PipelineCache` when the creation of a GPU pipeline object failed.\n#[expect(missing_docs, reason = \"Enum variants are self-explanatory\")]\n#[derive(Error, Debug)]\npub enum ShaderCacheError {\n    #[error(\n        \"Pipeline could not be compiled because the following shader could not be loaded: {0:?}\"\n    )]\n    ShaderNotLoaded(AssetId<Shader>),\n    #[error(\"Failed to process shader:\\n{0}\")]\n    ProcessShaderError(String),\n    #[error(\"Shader import not yet available.\")]\n    ShaderImportNotYetAvailable,\n    #[error(\"Could not create shader module: {0}\")]\n    CreateShaderModule(String),\n}\n\n#[cfg(test)]\nmod tests {\n    use super::*;\n\n    fn test_cache() -> ShaderCache<String, ()> {\n        ShaderCache::new((), |_, source, _| match source {\n            ShaderCacheSource::Wgsl(wgsl) => Ok(wgsl),\n            _ => panic!(\"expected wgsl output\"),\n        })\n    }\n","sourceCodeStart":524,"sourceCodeEnd":560,"githubUrl":"https://github.com/bevyengine/bevy/blob/227d3a6c661b3bdf3020d3e8290b5a6ffd0226f7/crates/bevy_shader/src/shader_cache.rs#L524-L560","documentation":"ShaderCacheError::ProcessShaderError is returned by ShaderCache::get when the Wesl compiler (wesl::compile_sourcemap) fails to process a shader whose source is Source::Wesl. The wrapped string is the raw Wesl compiler error. It is also returned directly when a Wesl shader's import_path cannot be parsed into a module path (\"Wesl shader `...` has a malformed import path\"). PipelineCache logs the error and marks the pipeline as errored; the app keeps running but that pipeline never renders.","triggerScenarios":"Calling ShaderCache::get (directly or via PipelineCache pipeline creation) on a Wesl shader that fails wesl::compile_sourcemap with a non-module-not-found error: WGSL/Wesl syntax errors, duplicate declarations, or a const in the shader colliding with an integer shader def (the cache auto-injects `const name = value;` for every ShaderDefVal::Int/UInt def, see shader_cache.rs:277-280), or a Wesl asset whose import_path wesl_module_path() cannot parse.","commonSituations":"Typos introduced while hot-reloading .wesl shader files; declaring constants in shader code that are also passed as integer shader_defs; migrating shaders from naga-oil `#import` preprocessing to Wesl import syntax across Bevy upgrades; passing shader defs whose names clash with Wesl reserved words.","solutions":["Read the embedded compiler message first — it names the file, line, and construct the Wesl compiler rejected","Fix the reported syntax error or malformed import path in the .wesl source","Remove `const` declarations that duplicate integer/uint shader defs; they are injected automatically from ShaderDefVal::Int/UInt","Verify every import path matches the actual asset path of the imported shader","If hot-reload state looks stale, restart the app to force a full shader recompile"],"exampleFix":"// before — ProcessShaderError: name 'PIXEL_RATIO' is already defined\n// (the integer shader def already injects `const PIXEL_RATIO = 2;`)\nconst PIXEL_RATIO = 2u;\nfn fs(in: VertexOutput) -> vec4<f32> {\n    let s = in.pos.x * f32(PIXEL_RATIO);\n    return vec4<f32>(s, 0.0, 0.0, 1.0);\n}\n\n// after — rely on the injected constant, do not redeclare it\nfn fs(in: VertexOutput) -> vec4<f32> {\n    let s = in.pos.x * f32(PIXEL_RATIO);\n    return vec4<f32>(s, 0.0, 0.0, 1.0);\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match shader_cache.get(pipeline_id, shader_id, &shader_defs) {\n    Ok(module) => { /* use module */ }\n    Err(ShaderCacheError::ProcessShaderError(msg)) => {\n        error!(\"shader compile failed, skipping pipeline: {msg}\");\n        // fall back to a known-good pipeline or mark the object unrenderable\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Lint shader assets in CI by compiling .wesl sources with the wesl compiler so mistakes fail the build, not the run","Never declare `const` names that are also passed as ShaderDefVal::Int/UInt defs — the cache injects them automatically","Keep import paths in shaders identical to the imported asset paths"],"tags":["bevy","shader","wesl","wgsl","pipeline","shader-defs"],"backgroundTag":"shader-compilation-failed","analyzedSha":"227d3a6c661b3bdf3020d3e8290b5a6ffd0226f7","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-09T01:17:15.007Z"}