bevyengine/bevy · error · GltfError

invalid glTF file: {0}

Error message

invalid glTF file: {0}

What it means

GltfError::Gltf wraps any gltf::Error via #[from]. It is produced when the gltf crate fails to parse or validate the file in GltfLoader::load (JSON syntax errors, glTF 2.0 spec violations, bad GLB chunk headers, unsupported version), and is also used for hand-built gltf::Error::Io cases such as the non-UTF-8 filename check at loader/mod.rs:279. The inner gltf::Error carries the precise cause, so always inspect it rather than the wrapper.

Source

Thrown at crates/bevy_gltf/src/loader/mod.rs:93

        texture::{texture_sampler, texture_transform_to_affine2},
    },
};
use crate::convert_coordinates::GltfConvertCoordinates;

/// Must match [`MAX_JOINTS`](https://docs.rs/bevy/latest/bevy/pbr/constant.MAX_JOINTS.html)
pub const MAX_JOINTS: usize = 256;

/// An error that occurs when loading a glTF file.
#[derive(Error, Debug)]
pub enum GltfError {
    /// Unsupported primitive mode.
    #[error("unsupported primitive mode")]
    UnsupportedPrimitive {
        /// The primitive mode.
        mode: Mode,
    },
    /// Invalid glTF file.
    #[error("invalid glTF file: {0}")]
    Gltf(#[from] gltf::Error),
    /// Binary blob is missing.
    #[error("binary blob is missing")]
    MissingBlob,
    /// Decoding the base64 mesh data failed.
    #[error("failed to decode base64 mesh data")]
    Base64Decode(#[from] base64::DecodeError),
    /// Unsupported buffer format.
    #[error("unsupported buffer format")]
    BufferFormatUnsupported,
    /// The buffer URI was unable to be resolved with respect to the asset path.
    #[error("invalid buffer uri: {0}. asset path error={1}")]
    InvalidBufferUri(String, ParseAssetPathError),
    /// Invalid image mime type.
    #[error("invalid image mime type: {0}")]
    #[from(ignore)]
    InvalidImageMimeType(String),
    /// Error when loading a texture. Might be due to a disabled image file format feature.

View on GitHub (pinned to 396ca72708)

Solutions

1. Run the file through gltf-validator (or the gltf crate CLI) to get the exact spec violation.
2. Check the asset is real binary/JSON: GLB files start with magic "glTF"; a git-LFS pointer starts with "version https://git-lfs".
3. Confirm the exporter targets glTF 2.0 and re-export.
4. If the path is the problem (inner error mentions 'Gltf file name invalid'), rename the file to valid UTF-8.

Example fix

// before: load blindly
let h = asset_server.load("models/scene.gltf");
// after: cheap pre-validation of the container
let bytes = std::fs::read("assets/models/scene.gltf")?;
let doc = gltf::Gltf::from_slice(&bytes)?; // surfaces parse/spec errors early
assert!(doc.version() == "2.0");

let bytes = std::fs::read(&path)?;
// fail fast on LFS pointers / html error pages
if !bytes.starts_with(b"glTF") && bytes.first() != Some(&b'{') {
    anyhow::bail!("not a glTF file: {}", path.display());
}
gltf::Gltf::from_slice(&bytes)?; // parse + spec-validate before bevy loads it

fn is_gltf_parse_error(err: &GltfError) -> bool {
    matches!(err, GltfError::Gltf(_))
}

match err {
    GltfError::Gltf(inner) => {
        error!("invalid glTF file: {inner}"); // inner names the exact JSON/spec problem
        skip_asset();
    }
    other => return Err(other.into()),
}

When it happens

Trigger: GltfLoader::load feeding malformed JSON to gltf::Gltf::from_reader; a .glb whose header/chunk lengths disagree with the actual bytes; json.asset.version below "2.0"; a non-UTF-8 asset path hitting the to_str() check at mod.rs:279; reading a git-LFS pointer file (small text) as a glTF binary.

Common situations: Truncated or partially downloaded models, git-LFS files not smudged, files written by non-conforming exporters, glTF 1.0 assets from old asset stores, or pipeline scripts that mangle encoding.

Related errors

• ParamSet parameter validation failed: {err}
• unsupported primitive mode
• binary blob is missing
• failed to decode base64 mesh data
• unsupported buffer format

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