bevyengine/bevy · error · CachedSceneError

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

Error message

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.

What it means

Runtime error returned by ResolvedScene::include_cached. For correctness the cached scene must be included before any Templates or related scenes are added to the ResolvedScene, because duplicate-template skipping and layering are computed relative to the cached scene. Including it late returns CachedSceneError::LateCached with the late asset's id and path.

Source

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

    /// 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>>,
    },
}

/// An error produced when applying a [`ResolvedScene`].
#[derive(Error, Debug)]
pub enum ApplySceneError {
    /// Caused when a [`Template`] fails to build
    #[error("Failed to build a Template in the current Scene: {0}")]
    TemplateBuildError(BevyError),
    /// Caused when the cached [`ResolvedScene`] fails to apply a [`ResolvedScene`].
    #[error("Failed to apply the cached Scene (asset path: \"{cached:?}\"): {error}")]
    CachedSceneApplyError {
        /// The asset path of the cached scene that failed to apply.

View on GitHub (pinned to 396ca72708)

Solutions

1. Call include_cached as the very first operation on the ResolvedScene, before any content that adds templates or related scenes
2. In a custom Scene::resolve impl, include the cached scene before resolving the rest of the BSN content
3. If you no longer need caching for this scene, skip include_cached entirely and resolve everything normally

Example fix

// before
impl Scene for MyScene {
    fn resolve(self, ctx: &mut ResolveContext) -> Result<ResolvedScene> {
        let mut resolved = self.inner_bsn.resolve(ctx)?; // adds templates first
        resolved.include_cached(self.cached)?;           // LateCached
        Ok(resolved)
    }
}

// after
impl Scene for MyScene {
    fn resolve(self, ctx: &mut ResolveContext) -> Result<ResolvedScene> {
        let mut resolved = ResolvedScene::default();
        resolved.include_cached(self.cached)?; // cached first
        self.inner_bsn.resolve_into(ctx, &mut resolved)?;
        Ok(resolved)
    }
}

if let Err(CachedSceneError::LateCached { id, path }) = resolved.include_cached(handle) {
    // rebuild the ResolvedScene from scratch, including the cached scene FIRST
}

When it happens

Trigger: Adding templates or relationship scenes to a ResolvedScene (e.g. by resolving scene content that produces them) and only afterwards calling include_cached. include_cached checks self.cached is unset AND that templates/related scenes are empty; non-empty state yields LateCached.

Common situations: Custom Scene::resolve implementations that build content first and append the cached include at the end; refactoring that moves the include_cached call; manual ResolvedScene construction in tests.

Related errors

• Attempted to include a second cached scene (id {id:?}, path:
• Cannot cache Scene function with arguments
• Failed to build a Template in the current Scene: {0}
• Failed to apply the cached Scene (asset path: "{cached:?}"):
• The cached scene (id: {id:?}, path: "{path:?}") does not exi

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