{"record":{"id":"f0150495a8fb5391","repo":"bevyengine/bevy","slug":"gltf-file-name-invalid","errorCode":null,"errorMessage":"Gltf file name invalid","messagePattern":"Gltf file name invalid","errorType":"exception","errorClass":"GltfError","httpStatus":null,"severity":"error","filePath":"crates/bevy_gltf/src/loader/mod.rs","lineNumber":279,"sourceCode":"        } else {\n            gltf::Gltf::from_slice_without_validation(bytes)?\n        };\n\n        // clone extensions to start with a fresh processing state\n        let mut extensions = loader.extensions.read().await.clone();\n\n        // Extensions can have data on the \"root\" of the glTF data.\n        // Let extensions process the root data for the extension ids\n        // they've subscribed to.\n        for extension in extensions.iter_mut() {\n            extension.on_root(load_context, &gltf, settings);\n        }\n\n        let file_name = load_context\n            .path()\n            .path()\n            .to_str()\n            .ok_or(GltfError::Gltf(gltf::Error::Io(Error::new(\n                std::io::ErrorKind::InvalidInput,\n                \"Gltf file name invalid\",\n            ))))?\n            .to_string();\n        let buffer_data = load_buffers(&gltf, load_context).await?;\n\n        let linear_textures = get_linear_textures(&gltf.document);\n\n        #[cfg(feature = \"bevy_animation\")]\n        let paths = if settings.load_animations {\n            let mut paths = HashMap::<usize, (usize, Vec<Name>)>::default();\n            for scene in gltf.scenes() {\n                for node in scene.nodes() {\n                    let root_index = node.index();\n                    collect_path(&node, &[], &mut paths, root_index, &mut HashSet::default());\n                }\n            }\n            paths","sourceCodeStart":261,"sourceCodeEnd":297,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_gltf/src/loader/mod.rs#L261-L297","documentation":"At loader/mod.rs:279 the loader converts the asset path with Path::to_str(), which returns None when the path contains bytes invalid in UTF-8; that None is packed into GltfError::Gltf(gltf::Error::Io(InvalidInput, \"Gltf file name invalid\")). So despite the wrapper this is specifically a non-UTF-8 filename/directory problem, not a content problem. Most common on Windows (WTF-8 paths) and after unzipping archives created with legacy encodings.","triggerScenarios":"Loading a glTF whose filename or any parent directory contains non-UTF-8 bytes (e.g. Latin-1 accented characters from an old zip, or mis-decoded byte sequences); GltfLoader::load reaching the file_name step after root-extension processing.","commonSituations":"Unzipping purchased model packs whose names use legacy code pages; files created by scripts from unvalidated byte strings; cross-platform asset drops onto Windows.","solutions":["Rename the file and every parent folder to valid UTF-8/ASCII.","Re-extract archives with a tool honoring the UTF-8 flag.","Sanitize asset paths at import time in your tooling (lossy-convert then rename on disk)."],"exampleFix":"# (before) name contains invalid UTF-8 bytes\nassets/models/bad$'\\xff'$'\\xf6'name.gltf\n# (after)\nmv assets/models/bad* assets/models/scene.gltf","handlingStrategy":"validation","validationCode":"fn path_loadable(path: &std::path::Path) -> bool {\n    path.to_str().is_some() // same check the loader performs at loader/mod.rs:279\n}","typeGuard":"fn is_utf8_path(p: &std::path::Path) -> bool {\n    p.to_str().is_some()\n}","tryCatchPattern":"match err {\n    GltfError::Gltf(gltf::Error::Io(ref io)) if io.to_string().contains(\"file name invalid\") => {\n        error!(\"asset path is not valid UTF-8; rename the file/folder\");\n    }\n    other => return Err(other.into()),\n}","preventionTips":["Normalize asset filenames to ASCII/UTF-8 at import.","Extract zips with UTF-8-aware tools.","Reject non-UTF-8 paths in asset tooling before they reach Bevy."],"tags":["gltf","path","utf-8","filename","bevy"],"backgroundTag":"non-utf8-file-path","analyzedSha":"396ca727080776bd313bb892423b7d94e03b81b4","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-09T01:17:15.007Z"}