bevyengine/bevy · error · ShaderLoaderError

Could not parse shader: {0}

Error message

Could not parse shader: {0}

What it means

ShaderLoaderError::Parse from the ShaderLoader asset loader. The .wgsl/.wesl file's bytes were not valid UTF-8, so String::from_utf8 failed and the FromUtf8Error is wrapped with 'Could not parse shader'. (Despite the name, this is an encoding error, not a syntax error — WESL syntax problems surface later, in shader compilation.)

Source

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

        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,
        reader: &mut dyn Reader,
        settings: &Self::Settings,

View on GitHub (pinned to 396ca72708)

Solutions

1. Re-save the shader file as UTF-8 (without BOM issues) in your editor
2. Check the file extension matches the actual content — .spv binaries must use .spv
3. If the file is generated, fix the generator to emit UTF-8 text

// fail fast on non-UTF-8 shader sources:
if let Ok(bytes) = std::fs::read(&path) {
    if std::str::from_utf8(&bytes).is_err() {
        // re-encode as UTF-8 before the loader sees it
    }
}

When it happens

Trigger: Loading a .wgsl or .wesl file that contains non-UTF-8 bytes: a binary file with the wrong extension, a non-UTF-8 encoding (latin-1), or corrupted bytes. from_utf8(bytes)? fails during ShaderLoader::load.

Common situations: Renaming a binary/compiled artifact to .wgsl; editors or pipelines saving shaders in a legacy encoding; a .spv file mislabeled as .wgsl.

Related errors

• Could not load shader: {0}
• unhandled extension: {ext}
• Gltf file name invalid
• RenderPipelineDescriptor has no FragmentState configured
• Enable feature "shader_format_spirv" to use SPIR-V shaders

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