bevyengine/bevy · error

Query does not match the current entity

Error message

Query does not match the current entity

What it means

Panics in EntityRef::components<Q> when the entity does not satisfy the query Q (e.g. a required component or filter is missing), so the query has no match for this particular entity.

Source

Thrown at crates/bevy_ecs/src/world/entity_access/entity_ref.rs:287

    #[inline]
    pub fn get_by_id<F: DynamicComponentFetch>(
        &self,
        component_ids: F,
    ) -> Result<F::Ref<'w>, EntityComponentError> {
        // SAFETY: We have read-only access to all components of this entity.
        unsafe { component_ids.fetch_ref(self.cell) }
    }

    /// Returns read-only components for the current entity that match the query `Q`.
    ///
    /// # Panics
    ///
    /// If the entity does not have the components required by the query `Q`.
    pub fn components<Q: ReadOnlyQueryData + ReleaseStateQueryData + SingleEntityQueryData>(
        &self,
    ) -> Q::Item<'w, 'static> {
        self.get_components::<Q>()
            .expect("Query does not match the current entity")
    }

    /// Returns read-only components for the current entity that match the query `Q`,
    /// or `None` if the entity does not have the components required by the query `Q`.
    pub fn get_components<Q: ReadOnlyQueryData + ReleaseStateQueryData + SingleEntityQueryData>(
        &self,
    ) -> Result<Q::Item<'w, 'static>, QueryAccessError> {
        // SAFETY:
        // - We have read-only access to all components of this entity.
        // - The query is read-only, and read-only references cannot have conflicts.
        unsafe { self.cell.get_components::<Q>() }
    }

    /// Returns the source code location from which this entity has been spawned.
    pub fn spawned_by(&self) -> MaybeLocation {
        self.cell.spawned_by()
    }

View on GitHub (pinned to 396ca72708)

Solutions

1. Use get_components::<Q>() which returns an Option instead of panicking
2. Check entity.contains::<T>() / matches the filter before calling
3. Ensure the component is actually inserted on the entity beforehand

When it happens

Trigger: Thrown at crates/bevy_ecs/src/world/entity_access/entity_ref.rs:287 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/8f0fbbd2ec6d6864. Report an issue: GitHub.