{"record":{"id":"a31ccd3d90e8249d","repo":"bevyengine/bevy","slug":"failed-to-load-file-0","errorCode":null,"errorMessage":"failed to load file: {0}","messagePattern":"failed to load file: (.+?)","errorType":"exception","errorClass":"GltfError","httpStatus":null,"severity":"error","filePath":"crates/bevy_gltf/src/loader/mod.rs","lineNumber":138,"sourceCode":"    /// Failed to load asset from an asset path.\n    #[error(\"failed to load asset from an asset path: {0}\")]\n    AssetLoadError(#[from] AssetLoadError),\n    /// Missing sampler for an animation.\n    #[error(\"Missing sampler for animation {0}\")]\n    #[from(ignore)]\n    MissingAnimationSampler(usize),\n    /// Failed to generate tangents.\n    #[error(\"failed to generate tangents: {0}\")]\n    GenerateTangentsError(#[from] bevy_mesh::GenerateTangentsError),\n    /// Failed to generate morph targets.\n    #[error(\"failed to generate morph targets: {0}\")]\n    MorphTarget(#[from] bevy_mesh::morph::MorphBuildError),\n    /// Circular children in Nodes\n    #[error(\"GLTF model must be a tree, found cycle instead at node indices: {0:?}\")]\n    #[from(ignore)]\n    CircularChildren(String),\n    /// Failed to load a file.\n    #[error(\"failed to load file: {0}\")]\n    Io(#[from] Error),\n}\n\n/// Loads glTF files with all of their data as their corresponding bevy representations.\n#[derive(TypePath)]\npub struct GltfLoader {\n    /// List of compressed image formats handled by the loader.\n    pub supported_compressed_formats: CompressedImageFormats,\n    /// Custom vertex attributes that will be recognized when loading a glTF file.\n    ///\n    /// Keys must be the attribute names as found in the glTF data, which must start with an underscore.\n    /// See [this section of the glTF specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#meshes-overview)\n    /// for additional details on custom attributes.\n    pub custom_vertex_attributes: HashMap<Box<str>, MeshVertexAttribute>,\n    /// Arc to default [`ImageSamplerDescriptor`].\n    pub default_sampler: Arc<Mutex<ImageSamplerDescriptor>>,\n    /// The default glTF coordinate conversion setting. This can be overridden\n    /// per-load by [`GltfLoaderSettings::convert_coordinates`].","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_gltf/src/loader/mod.rs#L120-L156","documentation":"GltfError::Io (#[from] std::io::Error) covers filesystem failures while reading the glTF file bytes in GltfLoader::load (the loader reads through io::Reader), and any io::Error raised inside the gltf parse stage. Typical kinds: NotFound, PermissionDenied, UnexpectedEof.","triggerScenarios":"asset_server.load(\"models/x.gltf\") where the path does not exist under an asset root; unreadable file permissions; file truncated mid-download or mid-write during hot-reload; io errors bubbling out of gltf::Gltf::from_reader.","commonSituations":"Wrong path or filename casing, assets not copied into the assets folder, sandboxed/managed environments denying reads, editor writing the file while the app loads it.","solutions":["Verify the exact path (and case) exists under the asset root the AssetSource was configured with.","Fix permissions or sandbox rules for the asset directory.","For truncated/lock issues during development, re-save the file or reload after the write completes.","Retry once for transient failures (network-mounted asset sources)."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"fn asset_readable(asset_root: &std::path::Path, rel: &str) -> std::io::Result<()> {\n    let p = asset_root.join(rel.trim_start_matches('/'));\n    std::fs::metadata(&p)?; // NotFound/PermissionDenied surface here, before bevy loads\n    Ok(())\n}","typeGuard":"fn is_not_found(err: &GltfError) -> bool {\n    matches!(err, GltfError::Io(e) if e.kind() == std::io::ErrorKind::NotFound)\n}","tryCatchPattern":"match err {\n    GltfError::Io(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => {\n        warn!(\"truncated read, retrying after download completes\");\n        retry_load();\n    }\n    GltfError::Io(e) => error!(\"glTF io error: {e}\");\n    other => return Err(other.into()),\n}","preventionTips":["Verify paths (and casing) under the configured asset root before load.","Keep asset directories readable by the app sandbox/user.","For hot-reload, save atomically (write temp, rename) to avoid partial reads."],"tags":["gltf","io","file-not-found","bevy"],"backgroundTag":"file-io-error","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"}