bevyengine/bevy · error · InvalidEntityError

The entity with ID {entity} is invalid; its index now has ge

Error message

The entity with ID {entity} is invalid; its index now has generation {current_generation}.

What it means

Display message for the invalid-entity error (used by SpawnError::Invalid and friends): the Entity handle's generation is stale relative to the allocator — its index now holds a newer generation, meaning the referenced entity was despawned (or never existed at that generation). The message reports both the stale handle and the current generation.

Source

Thrown at crates/bevy_ecs/src/entity/mod.rs:1125

    }
}

/// An error that occurs when a specified [`Entity`] can not be spawned.
#[derive(thiserror::Error, Debug, Clone, Copy, PartialEq, Eq)]
pub enum SpawnError {
    /// The [`Entity`] to spawn was invalid.
    /// It probably had the wrong generation or was created erroneously.
    #[error("Invalid id: {0}")]
    Invalid(InvalidEntityError),
    /// The [`Entity`] to spawn was already spawned.
    #[error("The entity can not be spawned as it already has a location.")]
    AlreadySpawned,
}

/// An error that occurs when a specified [`Entity`] does not exist in the entity id space.
/// See [module](crate::entity) docs for more about entity validity.
#[derive(thiserror::Error, Debug, Clone, Copy, PartialEq, Eq)]
#[error(
    "The entity with ID {entity} is invalid; its index now has generation {current_generation}."
)]
pub struct InvalidEntityError {
    /// The entity's ID.
    pub entity: Entity,
    /// The generation of the [`EntityIndex`], which did not match the requested entity.
    pub current_generation: EntityGeneration,
}

/// An error that occurs when a specified [`Entity`] is certain to be valid and is expected to be spawned but is not spawned yet.
/// This includes when an [`EntityIndex`] is requested but is not spawned, since each index always corresponds to exactly one valid entity.
#[derive(thiserror::Error, Debug, Clone, Copy, PartialEq, Eq)]
pub struct EntityValidButNotSpawnedError {
    /// The entity's ID.
    pub entity: Entity,
    /// The location of what last despawned the entity.
    pub location: MaybeLocation<&'static Location<'static>>,
}

View on GitHub (pinned to 396ca72708)

Solutions

1. Drop stale Entity handles and re-query for the entity by components or relationships
2. Validate handles with Entities::contains or Query-based checks before use
3. Track despawn events (on_remove hooks or observers) to invalidate stored ids proactively

When it happens

Trigger: Thrown at crates/bevy_ecs/src/entity/mod.rs:1125 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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