{"record":{"id":"d8666d5d8592c1fd","repo":"bevyengine/bevy","slug":"shader-import-not-yet-available","errorCode":null,"errorMessage":"Shader import not yet available.","messagePattern":"Shader import not yet available\\.","errorType":"exception","errorClass":"ShaderCacheError","httpStatus":null,"severity":"warning","filePath":"crates/bevy_shader/src/shader_cache.rs","lineNumber":544,"sourceCode":"    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\n    #[test]\n    fn import_resolution() {","sourceCodeStart":526,"sourceCodeEnd":562,"githubUrl":"https://github.com/bevyengine/bevy/blob/227d3a6c661b3bdf3020d3e8290b5a6ffd0226f7/crates/bevy_shader/src/shader_cache.rs#L526-L562","documentation":"ShaderCacheError::ShaderImportNotYetAvailable is a transient condition returned by ShaderCache::get when a shader's asset-path imports have not all resolved yet (n_asset_imports != n_resolved_asset_imports), or when Wesl compilation fails with a module-not-found error (shader_cache.rs:294-306, after a one-time `warn!` \"Shader `...` has an unresolved import\"). PipelineCache treats it as 'waiting' and retries on later frames; it only becomes a permanent stall if the import can never resolve (e.g. wrong path).","triggerScenarios":"Using a shader asset the same frame it is created while its ShaderImport::AssetPath dependencies are still loading; Wesl code importing a module whose backing asset is not yet registered; hot-reloading that adds a new import; a typo'd import path so resolution never succeeds.","commonSituations":"Spawning render objects immediately after asset_server.load() of a shader that imports other shader assets; editor/hot-reload workflows; import paths with wrong file names or missing .wesl extension; first frame after adding new shader files to the project.","solutions":["Do nothing if transient — the cache retries every frame and the pipeline appears once imports load","If the pipeline never appears, look for the one-time warning 'Shader `...` has an unresolved import' and fix the import path to match the imported shader's real asset path","Make sure imported shader assets themselves are loaded and registered before relying on the importing shader","For Wesl shaders, ensure import_path is a well-formed module path resolvable by wesl_module_path"],"exampleFix":"// before — import never resolves: file is shaders/common_lighting.wesl\nimports: vec![ShaderImport::AssetPath(\"shaders/common.wesl\".into())]\n\n// after — path matches the imported shader's actual asset path\nimports: vec![ShaderImport::AssetPath(\"shaders/common_lighting.wesl\".into())]","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"// PipelineCache already retries; when calling ShaderCache directly:\nmatch shader_cache.get(id, defs) {\n    Err(ShaderCacheError::ShaderImportNotYetAvailable) => { /* requeue for next frame */ }\n    Err(ShaderCacheError::ProcessShaderError(msg)) => { error!(\"{msg}\"); }\n    other => other?,\n}","preventionTips":["Load shader assets and their imports together and wait for dependencies before spawning render objects that use them","Watch for the one-time 'unresolved import' warning — a permanent stall means a wrong path, not slow loading"],"tags":["bevy","shader","import","asset-loading","wesl","pipeline"],"backgroundTag":"shader-import-unresolved","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"}