bevyengine/bevy · error · AddAsyncError

An error occurred while resolving an asset added by `add_asy

Error message

An error occurred while resolving an asset added by `add_async`: {error}

What it means

AddAsyncError — the future registered via AssetServer::add_async completed but resolving the resulting asset into the server failed; the underlying error (e.g. missing loader for the produced type) is wrapped in the payload. Check that a loader/registration exists for the asset type produced by the async operation.

Source

Thrown at crates/bevy_asset/src/server/mod.rs:2311

impl AssetLoaderError {
    /// The path of the asset that failed to load.
    pub fn path(&self) -> &AssetPath<'static> {
        &self.path
    }

    /// The error the loader reported when attempting to load the asset.
    ///
    /// If you know the type of the error the asset loader returned, you can use
    /// [`BevyError::downcast_ref()`] to get it.
    pub fn error(&self) -> &BevyError {
        &self.error
    }
}

/// An error that occurs while resolving an asset added by `add_async`.
#[derive(Error, Debug, Clone)]
#[error("An error occurred while resolving an asset added by `add_async`: {error}")]
pub struct AddAsyncError {
    error: Arc<dyn core::error::Error + Send + Sync + 'static>,
}

/// An error that occurs when an [`AssetLoader`] is not registered for a given extension.
#[derive(Error, Debug, Clone, PartialEq, Eq)]
#[error("no `AssetLoader` found{}", format_missing_asset_ext(extensions))]
pub struct MissingAssetLoaderForExtensionError {
    extensions: Vec<String>,
}

/// An error that occurs when an [`AssetLoader`] is not registered for a given [`core::any::type_name`].
#[derive(Error, Debug, Clone, PartialEq, Eq)]
#[error("no `AssetLoader` found with the name '{type_name}'")]
pub struct MissingAssetLoaderForTypeNameError {
    /// The type name that was not found.
    pub type_name: String,
}

View on GitHub (pinned to 227d3a6c66)

Solutions

1. Handle the Result returned by add_async
2. Inspect the wrapped inner error for the root cause
3. Add retries or fallback asset paths for flaky async sources

When it happens

Trigger: Thrown at crates/bevy_asset/src/server/mod.rs:2296 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of bevyengine/bevy@227d3a6c66 (2026-08-20). Data as JSON: /api/errors/01accfc382d3943c. Report an issue: GitHub.