bevyengine/bevy · error · CachedSceneError

Attempted to include a second cached scene (id {id:?}, path:

Error message

Attempted to include a second cached scene (id {id:?}, path: {path:?}), which is not allowed.

What it means

Runtime error returned by ResolvedScene::include_cached. A ResolvedScene may reference at most one cached scene (a pre-resolved ScenePatch); calling include_cached a second time returns CachedSceneError::MultipleCached with the offending asset id and path. The single-cached-scene limit keeps the cached/resolved layering unambiguous.

Source

Thrown at crates/bevy_scene/src/resolved_scene.rs:590

    }
}

/// Information about a [`ResolvedScene`]'s cached scene.
#[derive(Debug)]
pub(crate) struct CachedSceneInfo {
    /// The handle of the cached scene.
    pub(crate) handle: Handle<ScenePatch>,
    /// Template types that occur in _both_ the current scene and its cached scene.
    /// This is used to skip insertion of these types when applying the cached
    /// resolved scene.
    pub(crate) duplicate_templates: HashSet<TypeId>,
}

/// The error returned by [`ResolvedScene::include_cached`].
#[derive(Error, Debug)]
pub enum CachedSceneError {
    /// Caused when attempting to include a second cached scene.
    #[error(
        "Attempted to include a second cached scene (id {id:?}, path: {path:?}), which is not allowed."
    )]
    MultipleCached {
        /// The asset id of the second cached scene.
        id: UntypedAssetId,
        /// The path of the second cached scene.
        path: Option<AssetPath<'static>>,
    },
    /// Caused when attempting to include a cached scene when a [`ResolvedScene`] already has [`Template`]s or related scenes.
    #[error("Attempted to include cached scene (id {id:?}, path: {path:?}), but the resolved scene already has templates. For correctness, the cached scene should always be included first.")]
    LateCached {
        /// The asset id of the cached scene that was included late.
        id: UntypedAssetId,
        /// The path of the cached scene that was included late.
        path: Option<AssetPath<'static>>,
    },
}

View on GitHub (pinned to 396ca72708)

Solutions

Restructure so each ResolvedScene includes exactly one cached scene: nest the second cached scene inside the first cached scene's own BSN/source instead of the outer scene
Drop caching for one of the two sub-scenes and resolve it normally as a related scene
Split the outer scene into two sibling scenes, each with its own cached include

Example fix

// before
let mut resolved = scene.resolve(&ctx)?;
resolved.include_cached(handle_a.clone())?;
resolved.include_cached(handle_b)?; // MultipleCached

// after
let mut resolved = scene.resolve(&ctx)?;
resolved.include_cached(handle_a.clone())?;
// handle_b is included inside the scene that produced handle_a

Defensive patterns

Strategy: try-catch

Validate before calling

// include_cached returns Result — track inclusion yourself:
let mut included_cached = false;
if !included_cached {
    resolved.include_cached(handle.clone())?;
    included_cached = true;
}

Try / catch

match resolved.include_cached(handle) {
    Ok(()) => {}
    Err(CachedSceneError::MultipleCached { id, path }) => {
        // merge the extra cached scene upstream instead of including it here
    }
    Err(e) => return Err(e.into()),
}

Prevention

Design scene composition so each ResolvedScene includes at most one cached scene
Nest additional cached scenes inside the cached scene's own source rather than the outer scene

When it happens

Trigger: Calling resolved.include_cached(handle_a) and then resolved.include_cached(handle_b) on the same ResolvedScene. The first call stores self.cached; the second call sees it already set and returns MultipleCached.

Common situations: Composing a scene out of two cached sub-scenes at resolve time; refactoring that adds a second ':' asset include without removing the first; hand-rolled resolve logic that loops over cached handles.

Related errors

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