bevyengine/bevy · error · ShaderLoaderError

Could not load shader: {0}

Error message

Could not load shader: {0}

What it means

ShaderLoaderError::Io from the ShaderLoader asset loader. Reading the shader file from disk failed and the std::io::Error is wrapped with a 'Could not load shader' prefix; the asset load transitions to LoadState::Failed with this error inside.

Source

Thrown at crates/bevy_shader/src/shader.rs:251

    /// The underlying source code string, unless it is SPIR-V.
    pub fn as_str(&self) -> &str {
        match self {
            Source::Wgsl(s) | Source::Wesl(s) => s,
            Source::SpirV(_) => panic!("spirv not yet implemented"),
        }
    }
}

/// The [`AssetLoader`] responsible for loading unprocessed shader assets.
#[derive(Default, TypePath)]
pub struct ShaderLoader;

/// An error encountered while loading a shader's source.
#[non_exhaustive]
#[derive(Debug, Error)]
#[expect(missing_docs, reason = "The variants are self-explanatory.")]
pub enum ShaderLoaderError {
    #[error("Could not load shader: {0}")]
    Io(#[from] std::io::Error),
    #[error("Could not parse shader: {0}")]
    Parse(#[from] alloc::string::FromUtf8Error),
}

/// Settings for loading shaders.
#[derive(serde::Serialize, serde::Deserialize, Debug, Default)]
pub struct ShaderSettings {
    /// The shader defs to apply when this shader is loaded.
    pub shader_defs: Vec<ShaderDefVal>,
}

impl AssetLoader for ShaderLoader {
    type Asset = Shader;
    type Settings = ShaderSettings;
    type Error = ShaderLoaderError;
    async fn load(
        &self,

View on GitHub (pinned to 396ca72708)

Solutions

1. Verify the path printed in the io error exists relative to your asset root
2. Fix permissions or mount the shader directory into the sandbox/CI environment
3. Check the AssetServer failed-loads channel to surface these errors instead of silently missing shaders

let path = std::path::Path::new(&shader_path);
if !path.exists() {
    // fail fast with a clear message before requesting the asset
}

When it happens

Trigger: Loading an asset handled by ShaderLoader (extensions .wgsl/.wesl/.spv) where the file cannot be read: missing file, permission denied, or an I/O error during read. The FromUtf8/load path bubbles the io::Error into this variant.

Common situations: Asset path typos; shaders outside the configured asset folder; file permissions in containers/CI; files deleted or renamed during hot-reload.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• failed to load file: {0}
• Failed to load image bytes: {0}
• Could not parse shader: {0}
• unhandled extension: {ext}
• RenderPipelineDescriptor has no FragmentState configured

AI-assisted analysis of bevyengine/bevy@396ca72708 (2026-08-20). Data as JSON: /api/errors/ecd8ae97226be3dc. Report an issue: GitHub.