{"record":{"id":"b4bd0c29cc441edd","repo":"bevyengine/bevy","slug":"invalid-gltf-file-0","errorCode":null,"errorMessage":"invalid glTF file: {0}","messagePattern":"invalid glTF file: (.+?)","errorType":"exception","errorClass":"GltfError","httpStatus":null,"severity":"error","filePath":"crates/bevy_gltf/src/loader/mod.rs","lineNumber":93,"sourceCode":"        texture::{texture_sampler, texture_transform_to_affine2},\n    },\n};\nuse crate::convert_coordinates::GltfConvertCoordinates;\n\n/// Must match [`MAX_JOINTS`](https://docs.rs/bevy/latest/bevy/pbr/constant.MAX_JOINTS.html)\npub const MAX_JOINTS: usize = 256;\n\n/// An error that occurs when loading a glTF file.\n#[derive(Error, Debug)]\npub enum GltfError {\n    /// Unsupported primitive mode.\n    #[error(\"unsupported primitive mode\")]\n    UnsupportedPrimitive {\n        /// The primitive mode.\n        mode: Mode,\n    },\n    /// Invalid glTF file.\n    #[error(\"invalid glTF file: {0}\")]\n    Gltf(#[from] gltf::Error),\n    /// Binary blob is missing.\n    #[error(\"binary blob is missing\")]\n    MissingBlob,\n    /// Decoding the base64 mesh data failed.\n    #[error(\"failed to decode base64 mesh data\")]\n    Base64Decode(#[from] base64::DecodeError),\n    /// Unsupported buffer format.\n    #[error(\"unsupported buffer format\")]\n    BufferFormatUnsupported,\n    /// The buffer URI was unable to be resolved with respect to the asset path.\n    #[error(\"invalid buffer uri: {0}. asset path error={1}\")]\n    InvalidBufferUri(String, ParseAssetPathError),\n    /// Invalid image mime type.\n    #[error(\"invalid image mime type: {0}\")]\n    #[from(ignore)]\n    InvalidImageMimeType(String),\n    /// Error when loading a texture. Might be due to a disabled image file format feature.","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_gltf/src/loader/mod.rs#L75-L111","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run the file through gltf-validator (or the gltf crate CLI) to get the exact spec violation.","Check the asset is real binary/JSON: GLB files start with magic \"glTF\"; a git-LFS pointer starts with \"version https://git-lfs\".","Confirm the exporter targets glTF 2.0 and re-export.","If the path is the problem (inner error mentions 'Gltf file name invalid'), rename the file to valid UTF-8."],"exampleFix":"// before: load blindly\nlet h = asset_server.load(\"models/scene.gltf\");\n// after: cheap pre-validation of the container\nlet bytes = std::fs::read(\"assets/models/scene.gltf\")?;\nlet doc = gltf::Gltf::from_slice(&bytes)?; // surfaces parse/spec errors early\nassert!(doc.version() == \"2.0\");","handlingStrategy":"try-catch","validationCode":"let bytes = std::fs::read(&path)?;\n// fail fast on LFS pointers / html error pages\nif !bytes.starts_with(b\"glTF\") && bytes.first() != Some(&b'{') {\n    anyhow::bail!(\"not a glTF file: {}\", path.display());\n}\ngltf::Gltf::from_slice(&bytes)?; // parse + spec-validate before bevy loads it","typeGuard":"fn is_gltf_parse_error(err: &GltfError) -> bool {\n    matches!(err, GltfError::Gltf(_))\n}","tryCatchPattern":"match err {\n    GltfError::Gltf(inner) => {\n        error!(\"invalid glTF file: {inner}\"); // inner names the exact JSON/spec problem\n        skip_asset();\n    }\n    other => return Err(other.into()),\n}","preventionTips":["Validate assets with gltf-validator in CI.","Check git-LFS smudging when glTFs come from git.","Pin exporters to glTF 2.0 and diff JSON after regenerating."],"tags":["gltf","bevy","parsing","validation"],"backgroundTag":"gltf-parse-error","analyzedSha":"396ca727080776bd313bb892423b7d94e03b81b4","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}