{"record":{"id":"253dd4461d3936c9","repo":"bevyengine/bevy","slug":"pipeline-could-not-be-compiled-because-the-followi","errorCode":null,"errorMessage":"Pipeline could not be compiled because the following shader could not be loaded: {0:?}","messagePattern":"Pipeline could not be compiled because the following shader could not be loaded: (.+?)","errorType":"exception","errorClass":"ShaderCacheError","httpStatus":null,"severity":"error","filePath":"crates/bevy_shader/src/shader_cache.rs","lineNumber":538,"sourceCode":"                }\n            }\n            _ => module_path.clone(),\n        }\n    }\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),","sourceCodeStart":520,"sourceCodeEnd":556,"githubUrl":"https://github.com/bevyengine/bevy/blob/227d3a6c661b3bdf3020d3e8290b5a6ffd0226f7/crates/bevy_shader/src/shader_cache.rs#L520-L556","documentation":"Variant of ShaderCacheError from the shader/pipeline cache. A pipeline could not be compiled because one of the shaders it references is not loaded — the AssetId given to the cache has no loaded Shader behind it. This usually means the pipeline was queued before the shader asset finished (or failed) loading.","triggerScenarios":"Creating/queueing a pipeline whose ShaderPatches or shader AssetIds were derived from weak/unloaded handles, or after the shader asset failed to load; the cache looks up the shader by id, finds nothing, and returns ShaderNotLoaded(id).","commonSituations":"Custom render pipelines initialized during plugin build before the asset server loads shaders; hot-reload evicting a shader; typos in shader asset paths so the load never completes.","solutions":["Hold strong handles to all shaders the pipeline needs until the pipeline is created","Wait for LoadState::Loaded on the shader handle (e.g. recursively_dependencies_loaded) before queueing the pipeline","Check the failed-loads channel to confirm the shader path actually resolves on disk"],"exampleFix":"// before\nlet shader = server.load_untyped(\"shader.wesl\");\nqueue_pipeline(shader.id()); // ShaderNotLoaded\n\n// after\nlet shader: Handle<Shader> = server.load(\"shader.wesl\");\nif server.load_state(&shader) == LoadState::Loaded {\n    queue_pipeline(shader);\n}","handlingStrategy":"validation","validationCode":"if server.load_state(&shader_handle) != bevy::asset::LoadState::Loaded {\n    // defer pipeline creation until the shader is loaded\n    return;\n}","typeGuard":null,"tryCatchPattern":"match pipeline_result {\n    Err(ShaderCacheError::ShaderNotLoaded(id)) => {\n        // re-queue the pipeline once the asset id reports Loaded\n    }\n    _ => {}\n}","preventionTips":["Store strong Handles to every shader a pipeline references until the pipeline compiles","Initialize custom render pipelines in systems that run after load state checks, not in plugin build()"],"tags":["bevy","shader","pipeline","asset","async"],"backgroundTag":"asset-not-yet-loaded","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"}