bevyengine/bevy · error · UnboundedAccessError

Access is unbounded

Error message

Access is unbounded

What it means

Error from UnboundedAccessError: an operation tried to enumerate/iterate the items included in an Access, but the Access is unbounded — it grants access to all components (e.g. via a broad &mut EntityMut or resource access), so there is no finite item set to iterate. The error type is the sentinel returned by such conversion/iteration attempts.

Source

Thrown at crates/bevy_ecs/src/query/access.rs:559

                ComponentAccessKind::Exclusive(index)
            } else {
                ComponentAccessKind::Shared(index)
            }
        });

        let archetypal = self
            .archetypal
            .difference(reads)
            .map(ComponentAccessKind::Archetypal);

        Ok(accesses.chain(archetypal))
    }
}

/// Error returned when attempting to iterate over items included in an [`Access`]
/// if the access excludes items rather than including them.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Error)]
#[error("Access is unbounded")]
pub struct UnboundedAccessError {
    /// [`Access`] is defined in terms of _excluding_ [exclusive](ComponentAccessKind::Exclusive)
    /// access.
    pub writes_inverted: bool,
    /// [`Access`] is defined in terms of _excluding_ [shared](ComponentAccessKind::Shared) and
    /// [exclusive](ComponentAccessKind::Exclusive) access.
    pub reads_inverted: bool,
}

/// Describes the level of access for a particular component as defined in an [`Access`].
#[derive(PartialEq, Eq, Hash, Debug, Clone, Copy)]
pub enum ComponentAccessKind {
    /// Archetypical access, such as `Has<Foo>`.
    Archetypal(ComponentId),
    /// Shared access, such as `&Foo`.
    Shared(ComponentId),
    /// Exclusive access, such as `&mut Foo`.
    Exclusive(ComponentId),

View on GitHub (pinned to 396ca72708)

Solutions

1. Narrow the access: query specific components instead of unbounded EntityMut access
2. Check Access::is_unbounded() before attempting to iterate its contents
3. Design the consumer to handle the unbounded case (error/skip) rather than assume enumeration is possible

When it happens

Trigger: Thrown at crates/bevy_ecs/src/query/access.rs:559 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/9fe95247337cd4b1. Report an issue: GitHub.