bevyengine/bevy · error · AssetLoadError::MissingAssetLoader

Could not find an asset loader matching: Asset Type: {asset_

Error message

Could not find an asset loader matching: Asset Type: {asset_type_id:?}; Path: {asset_path:?};

What it means

AssetLoadError::MissingAssetLoader is returned by the AssetServer when no registered AssetLoader handles the requested asset type for the given path. The server resolves loaders by asset type (when an asset type is specified) and cannot find one registered for that TypeId. This usually means the loader's plugin was never added to the app.

Source

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

    pub actual_asset_name: &'static str,
    /// The loader name used to load the asset.
    pub loader_name: &'static str,
}

/// An error that occurs during an [`Asset`] load.
#[derive(Error, Debug, Clone)]
#[expect(
    missing_docs,
    reason = "Adding docs to the variants would not add information beyond the error message and the names"
)]
pub enum AssetLoadError {
    #[error("Attempted to load an asset with an empty path \"{0}\".")]
    EmptyPath(AssetPath<'static>),
    #[error("Asset path \"{0}\" is unapproved. See UnapprovedPathMode for details.")]
    UnapprovedPath(AssetPath<'static>),
    #[error(transparent)]
    RequestedHandleTypeMismatch(#[from] Box<RequestedHandleTypeMismatchError>),
    #[error("Could not find an asset loader matching: Asset Type: {asset_type_id:?}; Path: {asset_path:?};")]
    MissingAssetLoader {
        asset_type_id: Option<TypeId>,
        asset_path: String,
    },
    #[error(transparent)]
    MissingAssetLoaderForExtension(#[from] MissingAssetLoaderForExtensionError),
    #[error(transparent)]
    MissingAssetLoaderForTypeName(#[from] MissingAssetLoaderForTypeNameError),
    #[error(transparent)]
    MissingAssetLoaderForTypeIdError(#[from] MissingAssetLoaderForTypeIdError),
    #[error(transparent)]
    AssetReaderError(#[from] AssetReaderError),
    #[error(transparent)]
    MissingAssetSourceError(#[from] MissingAssetSourceError),
    #[error(transparent)]
    MissingProcessedAssetReaderError(#[from] MissingProcessedAssetReaderError),
    #[error("Encountered an error while reading asset metadata bytes")]
    AssetMetaReadError,

View on GitHub (pinned to 227d3a6c66)

Solutions

1. Add the plugin that registers the loader (e.g. .add_plugins(GltfPlugin::default()) or your custom plugin with init_asset_loader)
2. Ensure init_asset_loader / register_asset_loader is called for your custom asset type
3. Check that the asset type in load::<T>() matches what the loader actually produces
4. Enable the feature flag or add the dependency for the loader crate you need

Example fix

// before
let handle: Handle<MyFormatAsset> = server.load("assets/data.myformat");
// no loader registered -> MissingAssetLoader
// after
App::new()
    .add_plugins((DefaultPlugins, MyFormatAssetPlugin)) // registers the loader
    .run();

// ensure the loader plugin is added before loading
App::new()
    .add_plugins(MyFormatAssetPlugin)
    .add_systems(Startup, setup);

fn loader_registered<T: Asset>(server: &AssetServer) -> bool {
    server.get_path_loader(&AssetPath::from_static("dummy")).is_ok()
        || std::any::TypeId::of::<T>() == std::any::TypeId::of::<T>() // load::<T> only after the T-producing plugin is added
}

match server.load_checked::<MyFormatAsset>("assets/data.myformat") {
    Ok(handle) => handle,
    Err(AssetLoadError::MissingAssetLoader { asset_type_id, asset_path }) => {
        error!("no loader for {asset_type_id:?} at {asset_path}; is the plugin added?");
        Handle::default()
    }
    Err(e) => panic!("asset load failed: {e}"),
}

When it happens

Trigger: Calling AssetServer::load::<MyAsset>(path) where no AssetLoader producing MyAsset was registered; loading a custom asset type whose loader plugin wasn't added; a type mismatch where the loaded handle's asset type differs from any registered loader's target type.

Common situations: Forgetting to add a plugin (e.g. GltfPlugin, ImagePlugin, or your own AssetLoader plugin) before loading; custom asset types where the loader registration (init_asset_loader) was missed; feature flags excluding the loader crate; renamed/moved asset types after a Bevy version upgrade so the registered type no longer matches.

Related errors

• missing texture atlas layout for the font
• missing texture for the font atlas
• Error while trying to read the world file: {0}
• Could not parse RON: {0}
• Each AssetId should have a corresponding asset

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