{"record":{"id":"dbc0b39cfb08d8c6","repo":"bevyengine/bevy","slug":"could-not-create-shader-module-0","errorCode":null,"errorMessage":"Could not create shader module: {0}","messagePattern":"Could not create shader module: (.+?)","errorType":"exception","errorClass":"ShaderCacheError","httpStatus":null,"severity":"error","filePath":"crates/bevy_shader/src/shader_cache.rs","lineNumber":546,"sourceCode":"        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\n    #[test]\n    fn import_resolution() {\n        let mut cache = test_cache();\n","sourceCodeStart":528,"sourceCodeEnd":564,"githubUrl":"https://github.com/bevyengine/bevy/blob/227d3a6c661b3bdf3020d3e8290b5a6ffd0226f7/crates/bevy_shader/src/shader_cache.rs#L528-L564","documentation":"ShaderCacheError::CreateShaderModule(description) is produced in bevy_render's create_shader_module helper (pipeline_cache.rs:144-170): a wgpu error scope with ErrorFilter::Validation is pushed around module creation, and any validation error is captured and returned as this variant. It means naga/wgpu (or the driver) rejected the final WGSL at module creation. On native the error is caught early; on wasm the browser APIs are async, so the app instead crashes inside wgpu.","triggerScenarios":"WGSL that passes preprocessing but fails naga/driver validation: using textureSample (implicit derivatives) in a @vertex entry point, unknown functions/types, bindings that do not match the bind group layouts, or feature-gated WGSL not supported by the adapter.","commonSituations":"Porting shaders from other APIs (HLSL/GLSL habits); @group/@binding indices drifting out of sync with layout changes; enabling experimental WGSL extensions on older drivers; validation rules tightening after a wgpu/Bevy upgrade.","solutions":["Read the wgpu validation description — it names the entry point and the rejected instruction","Move implicit-LOD texture reads in vertex stages to textureSampleLevel/textureLoad","Align @group/@binding annotations with your bind group layouts","Validate the WGSL offline with the naga CLI or naga validators to get exact source spans","Update wgpu/Bevy if validation rules changed"],"exampleFix":"// before — validation error: textureSample must only be used in fragment shaders\n@vertex\nfn vs_vs(vertex: VertexOutput) -> VertexOutput {\n    let light = textureSample(t_light_map, s_light_map, vertex.uv);\n    ...\n}\n\n// after — explicit level is valid in vertex stage\n@vertex\nfn vs_vs(vertex: VertexOutput) -> VertexOutput {\n    let light = textureSampleLevel(t_light_map, s_light_map, vertex.uv, 0.0);\n    ...\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match create_shader_module(device, descriptor, ValidateShader::Enabled) {\n    Ok(module) => module,\n    Err(ShaderCacheError::CreateShaderModule(desc)) => {\n        error!(\"wgpu rejected shader module: {desc}\");\n        fallback_module\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Validate WGSL offline with naga before shipping","Keep bind group layouts and @binding annotations in one reviewed place to avoid drift","Avoid implicit-LOD sampling in non-fragment stages"],"tags":["bevy","wgpu","wgsl","shader","naga","validation"],"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"}