bevyengine/bevy · error · LoadDirectError

Requested to load an asset path ({0:?}) with a subasset, but

Error message

Requested to load an asset path ({0:?}) with a subasset, but this is unsupported. See issue #18291

What it means

LoadDirectError::RequestedSubasset: the asset path being loaded ends in a subasset label (e.g. 'scene.gltf#Mesh0'), which the direct/nested load path does not support yet (bevy issue #18291). The whole asset must be loaded and the subasset selected afterwards.

Source

Thrown at crates/bevy_asset/src/loader.rs:351

            .insert(index, *self)
            .expect("the AssetIndex is still valid");
    }

    fn asset_type_name(&self) -> &'static str {
        core::any::type_name::<A>()
    }
}

/// An error that occurs when attempting an async load using [`NestedLoadBuilder`].
#[derive(Error, Debug)]
pub enum LoadDirectError {
    /// The asset path was empty.
    #[error("Attempted to load an asset with an empty path \"{0}\"")]
    EmptyPath(AssetPath<'static>),
    /// Loading an asset path with a subasset at the end is unsupported. See issue [#18291].
    ///
    /// [#18291]: https://github.com/bevyengine/bevy/issues/18291
    #[error("Requested to load an asset path ({0:?}) with a subasset, but this is unsupported. See issue #18291")]
    RequestedSubasset(AssetPath<'static>),
    /// A general [`AssetLoadError`] for an asset dependency.
    #[error("Failed to load dependency {dependency:?} {error}")]
    LoadError {
        /// Which dependency failed.
        dependency: AssetPath<'static>,
        /// The original error for that dependency.
        error: Box<AssetLoadError>,
    },
}

/// An error that occurs while deserializing [`AssetMeta`].
#[derive(Error, Debug, Clone, PartialEq, Eq)]
pub enum DeserializeMetaError {
    /// Failed to deserialize the asset metadata.
    #[error("Failed to deserialize asset meta: {0:?}")]
    DeserializeSettings(#[from] SpannedError),
    /// Failed to deserialize the minimal asset metadata.

View on GitHub (pinned to 396ca72708)

Solutions

1. Remove the #label from the path passed to the direct load and select the subasset from the loaded result instead
2. Track upstream issue bevyengine/bevy#18291 for subasset-aware direct loads
3. Restructure assets so the needed data is the primary asset

When it happens

Trigger: Thrown at crates/bevy_asset/src/loader.rs:351 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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