bevyengine/bevy · error · QueryEntityError

The query does not match entity {0}

Error message

The query does not match entity {0}

What it means

thiserror Display for QueryEntityError::QueryDoesNotMatch: Query::get/get_mut was called with an Entity whose archetype does not satisfy the query — either it lacks a queried component or a filter (With/Without/Added/etc.) excludes it. The archetype id pinpoints which table row mismatched; the message names the entity in {0}.

Source

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

use bevy_utils::prelude::DebugName;

use crate::{
    archetype::ArchetypeId,
    entity::{Entity, EntityNotSpawnedError},
};

/// An error that occurs when retrieving a specific [`Entity`]'s query result from [`Query`](crate::system::Query) or [`QueryState`](crate::query::QueryState).
// TODO: return the type_name as part of this error
#[derive(thiserror::Error, Clone, Copy, Debug, PartialEq, Eq)]
pub enum QueryEntityError {
    /// The given [`Entity`]'s components do not match the query.
    ///
    /// Either it does not have a requested component, or it has a component which the query filters out.
    #[error("The query does not match entity {0}")]
    QueryDoesNotMatch(Entity, ArchetypeId),
    /// 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),

View on GitHub (pinned to 396ca72708)

Solutions

1. Verify the entity actually has the queried components before calling get
2. Adjust the query filters (e.g. drop Without<> that excludes the archetype)
3. Use Query::contains_entity/get_many and branch on the Option/Result instead of assuming membership
4. Use an Option<Q> query parameter to tolerate absent components

When it happens

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