bevyengine/bevy · error · ResolveSceneError

Cannot resolve scene because the asset dependency {0} is not

Error message

Cannot resolve scene because the asset dependency {0} is not present. This could be because it isn't loaded yet, or because the asset does not exist. Consider using `queue_spawn_scene()` if you would like to wait for scene dependencies before spawning.

What it means

Variant of ResolveSceneError returned by Scene::resolve. The scene declared an asset dependency in Scene::register_dependencies, but the corresponding asset is not available from the AssetServer at resolve time — either still loading, or genuinely missing. The message points at queue_spawn_scene as the wait-aware alternative.

Source

Thrown at crates/bevy_scene/src/scene.rs:158

    /// Iterates the current dependencies.
    pub fn iter(&self) -> impl Iterator<Item = &SceneDependency> {
        self.0.iter()
    }
}

/// An asset dependency of a [`Scene`].
pub struct SceneDependency {
    /// The path of the asset.
    pub path: AssetPath<'static>,
    /// The type of the asset.
    pub type_id: TypeId,
}

/// An [`Error`] that occurs during [`Scene::resolve`].
#[derive(Error, Debug)]
pub enum ResolveSceneError {
    /// Caused when a dependency listed in [`Scene::register_dependencies`] is not available when calling [`Scene::resolve`]
    #[error("Cannot resolve scene because the asset dependency {0} is not present. This could be because it isn't loaded yet, or because the asset does not exist. Consider using `queue_spawn_scene()` if you would like to wait for scene dependencies before spawning.")]
    MissingSceneDependency(AssetPath<'static>),
    /// Caused when including a cached scene during [`Scene::resolve`] fails.
    #[error(transparent)]
    CachedSceneError(#[from] CachedSceneError),
    /// Caused when a [`Scene`]/[`SceneList`] is not present on the scene asset.
    #[error("The Scene/SceneList is not present on the scene asset. This is likely because the scene has already been resolved, which consumed the source scene")]
    MissingScene,
}

/// Context used by [`Scene`] implementations during [`Scene::resolve`].
pub struct ResolveContext<'a> {
    /// The current asset server
    pub assets: &'a AssetServer,
    /// The current [`ScenePatch`] asset collection
    pub patches: &'a Assets<ScenePatch>,
    /// The currently cached [`ScenePatch`], if there is one.
    pub cached: Option<&'a ScenePatch>,
}

View on GitHub (pinned to 396ca72708)

Solutions

  1. Use queue_spawn_scene instead of immediate spawn/resolve — it waits for dependencies
  2. Gate resolution on asset_server.recursively_dependencies_loaded(&handle) returning true
  3. Check the failing AssetPath in the error for typos or missing files, and fix the path in the scene source

Example fix

// before
let patch = ScenePatch::load(&server, scene);
patch.resolve(&server, &patches)?; // MissingSceneDependency

// after
let handle = server.add(ScenePatch::load(&server, scene));
if server.recursively_dependencies_loaded(&handle) {
    patches.get_mut(&handle).unwrap().resolve(&server, &patches)?;
} else {
    world.queue_spawn_scene(handle);
}
Defensive patterns

Strategy: validation

Validate before calling

if !server.recursively_dependencies_loaded(&handle) {
    world.queue_spawn_scene(handle);
    return Ok(());
}
// safe to resolve now

Try / catch

match patch.resolve(&server, &patches) {
    Err(ResolveSceneError::MissingSceneDependency(path)) => {
        // retry next frame or report the missing path
    }
    r => r?,
}

Prevention

When it happens

Trigger: Calling scene.resolve(...) (or ScenePatch::resolve) in the same frame the dependency was requested, before LoadState reaches Loaded; or referencing an asset path that does not exist on disk, so it never will load.

Common situations: Custom systems that resolve immediately after load without checking load state; typos in asset paths used inside BSN (':"scenes/level.scn"'); moving/renaming asset files without updating scene sources.

Related errors

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