bevyengine/bevy · error · QuerySingleError

Multiple entities fit the query {0}

Error message

Multiple entities fit the query {0}

What it means

thiserror Display for QuerySingleError::MultipleEntities: a single-result API (Query::single / single_mut) matched two or more entities, violating the exactly-one expectation. The query is not selective enough; {0} names the query type via DebugName.

Source

Thrown at crates/bevy_ecs/src/query/error.rs:35

    /// The given [`Entity`] is not spawned.
    #[error("{0}")]
    NotSpawned(#[from] EntityNotSpawnedError),
    /// The [`Entity`] was requested mutably more than once.
    ///
    /// See [`Query::get_many_mut`](crate::system::Query::get_many_mut) for an example.
    #[error("The entity with ID {0} was requested mutably more than once")]
    AliasedMutability(Entity),
}

/// An error that occurs when evaluating a [`Query`](crate::system::Query) or [`QueryState`](crate::query::QueryState) as a single expected result via
/// [`single`](crate::system::Query::single) or [`single_mut`](crate::system::Query::single_mut).
#[derive(Debug, thiserror::Error)]
pub enum QuerySingleError {
    /// No entity fits the query.
    #[error("No entities fit the query {0}")]
    NoEntities(DebugName),
    /// Multiple entities fit the query.
    #[error("Multiple entities fit the query {0}")]
    MultipleEntities(DebugName),
}

/// An error that occurs when creating a contiguous iterator from a non-dense [`Query`](crate::system::Query) or [`QueryState`](crate::query::QueryState) via
/// [`contiguous_iter`](crate::system::Query::contiguous_iter) or [`contiguous_iter_mut`](crate::system::Query::contiguous_iter_mut).
#[derive(Debug, thiserror::Error)]
#[error("Cannot contiguously iterate non-dense query {0}")]
pub struct QueryNotDenseError(pub DebugName);

#[cfg(test)]
mod test {
    use crate::{prelude::World, query::QueryEntityError};
    use bevy_ecs_macros::Component;

    #[test]
    fn query_does_not_match() {
        let mut world = World::new();

View on GitHub (pinned to 396ca72708)

Solutions

1. Tighten the query with With/Without filters or an Added<>/Changed<> qualifier
2. Use iter().next() or collect the matches when multiple results are acceptable
3. Enforce uniqueness at spawn time so only one matching entity exists

When it happens

Trigger: Thrown at crates/bevy_ecs/src/query/error.rs:35 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/6da4096a72e59d04. Report an issue: GitHub.