bevyengine/bevy · error · GltfError

failed to load asset from an asset path: {0}

Error message

failed to load asset from an asset path: {0}

What it means

GltfError::AssetLoadError (#[from] AssetLoadError) wraps a bevy_asset::AssetLoadError raised while loading a dependent asset during glTF processing — typically an image referenced by path (loaded through the asset server rather than read as raw bytes) whose own load failed, or a nested asset reference. The inner error identifies which dependency broke and why.

Source

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

    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.
    #[error("You may need to add the feature for the file format: {0}")]
    ImageError(#[from] TextureError),
    /// The image URI was unable to be resolved with respect to the asset path.
    #[error("invalid image uri: {0}. asset path error={1}")]
    InvalidImageUri(String, ParseAssetPathError),
    /// Failed to read bytes from an asset path.
    #[error("failed to read bytes from an asset path: {0}")]
    ReadAssetBytesError(#[from] ReadAssetBytesError),
    /// Failed to load asset from an asset path.
    #[error("failed to load asset from an asset path: {0}")]
    AssetLoadError(#[from] AssetLoadError),
    /// Missing sampler for an animation.
    #[error("Missing sampler for animation {0}")]
    #[from(ignore)]
    MissingAnimationSampler(usize),
    /// Failed to generate tangents.
    #[error("failed to generate tangents: {0}")]
    GenerateTangentsError(#[from] bevy_mesh::GenerateTangentsError),
    /// Failed to generate morph targets.
    #[error("failed to generate morph targets: {0}")]
    MorphTarget(#[from] bevy_mesh::morph::MorphBuildError),
    /// Circular children in Nodes
    #[error("GLTF model must be a tree, found cycle instead at node indices: {0:?}")]
    #[from(ignore)]
    CircularChildren(String),
    /// Failed to load a file.
    #[error("failed to load file: {0}")]
    Io(#[from] Error),

View on GitHub (pinned to 396ca72708)

Solutions

1. Inspect the inner AssetLoadError (Bevy logs the failing dependency path at ERROR) and fix that asset first.
2. Verify every file referenced by the glTF exists and loads standalone.
3. Embed textures into a GLB to collapse the dependency chain.
4. For custom AssetSources, confirm companion file paths are resolvable at runtime.

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

match err {
    GltfError::AssetLoadError(inner) => {
        error!("a dependency of this glTF failed to load: {inner}"); // fix the named asset first
    }
    other => return Err(other.into()),
}

When it happens

Trigger: A texture path resolved to a child asset whose loader errored (unsupported image format, missing file at load time, failed import in a processed-asset pipeline); chained glTF assets referencing each other with one broken link.

Common situations: External textures in formats without enabled features, partially copied asset folders, hot-reload picking up half-written files, processor configurations that skip companion assets.

Related errors

• unsupported primitive mode
• invalid glTF file: {0}
• 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/8e82afd56c26a84d. Report an issue: GitHub.