Enum ExecutionError 

#[non_exhaustive]
pub enum ExecutionError {
    StructuralMutationDuringIteration,
    BorrowConflict {
        component_id: ComponentID,
        held: AccessKind,
        requested: AccessKind,
    },
    InvalidQueryAccess {
        component_id: ComponentID,
        reason: InvalidAccessReason,
    },
    SelfChannelAlias {
        channel_id: ChannelID,
    },
    BoundaryAccessFailed {
        reason: BoundaryAccessFailure,
        id: BoundaryID,
    },
    DuplicateChannelRegistration {
        channel_id: ChannelID,
        existing_boundary: BoundaryID,
    },
    ChannelIdOverflow,
    MissingComponent {
        component_id: ComponentID,
    },
    QueryTypeMismatch {
        method: &'static str,
        access: AccessKind,
        index: usize,
        component_id: ComponentID,
        expected: &'static str,
        actual: &'static str,
    },
    DuplicateSystemId {
        system_id: SystemID,
    },
    UnknownSystemId {
        system_id: SystemID,
    },
    SelfSystemOrdering {
        system_id: SystemID,
    },
    SchedulerInvariantViolation,
    SchedulerCycle,
    LockPoisoned {
        what: &'static str,
    },
    GpuNotEnabled,
    GpuUnsupportedComponent {
        component_id: ComponentID,
        name: &'static str,
    },
    GpuInitFailed {
        message: Cow<'static, str>,
    },
    GpuDispatchFailed {
        message: Cow<'static, str>,
    },
    GpuMissingBuffer {
        archetype_id: ArchetypeID,
        component_id: ComponentID,
        access: GPUAccessMode,
    },
    InternalExecutionError,
    SystemRuntime(String),
}

Errors that occur during ECS execution and iteration.

These errors represent violations of ECS runtime safety rules detected dynamically by the engine.

Characteristics

• Caused by incorrect API usage
• Always deterministic
• Never indicate partial ECS mutation

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

StructuralMutationDuringIteration

Attempted to mutate ECS structure while iteration was active.

This includes spawning, despawning, adding/removing components, or calling with_exclusive during iteration.

BorrowConflict

Component borrow rules were violated at runtime.

Fields

component_id: ComponentID

Component whose borrow was violated.

held: AccessKind

Existing access mode already held.

requested: AccessKind

Access mode that was requested.

InvalidQueryAccess

A query declared invalid or contradictory component access.

Fields

component_id: ComponentID

The component whose access declaration was invalid.

reason: InvalidAccessReason

The specific reason the access was rejected.

SelfChannelAlias

A system declared the same channel in both its produces and consumes sets.

This is structurally unsound: the stage packer would place the system in a stage where it both produces and consumes the channel in one pass, so the consumes observation would read un-finalised channel data. Always a bug in the system’s AccessSets declaration.

Surfaced by AccessSets::validate at system-registration time.

Fields

channel_id: ChannelID

The channel ID that appeared in both produces and consumes.

BoundaryAccessFailed

An attempt to access a boundary resource via ECSReference::boundary failed because the BoundaryID was out of range or the stored resource’s concrete type did not match the requested type.

Distinct from ExecutionError::InternalExecutionError because boundary-access failures are caller-attributable: passing the wrong BoundaryID or the wrong type parameter R is a user-level bug, not an engine invariant violation.

Fields

reason: BoundaryAccessFailure

Which form the access failure took.

id: BoundaryID

The BoundaryID that was passed to ECSReference::boundary.

DuplicateChannelRegistration

Two boundary resources both declared ownership of the same ChannelID.

Channel IDs must be unique across all boundary resources so the scheduler can route finalise calls deterministically. This error is raised by ECSManager::register_boundary when the resource being registered claims a channel that is already owned by an earlier-registered resource.

Fields

channel_id: ChannelID

The channel ID that appeared in two resources.

existing_boundary: BoundaryID

The BoundaryID of the resource that already owned this channel.

ChannelIdOverflow

Channel ID allocation exhausted the u32 identifier space.

MissingComponent

A query attempted to access a component not present in a matched archetype.

Fields

component_id: ComponentID

The missing component identifier.

QueryTypeMismatch

A typed query helper was invoked with a Rust type that does not match the component type bound into the built query.

Fields

method: &'static str

Name of the helper that detected the mismatch.

access: AccessKind

Whether the mismatched column was read-only or writable.

index: usize

Column index within the query declaration order.

component_id: ComponentID

Runtime component identifier for the mismatched column.

expected: &'static str

Type name recorded when the query was built.

actual: &'static str

Type name requested by the typed helper.

DuplicateSystemId

The scheduler was given more than one system with the same ID.

System IDs are used as stable ordering keys in the execution graph, so duplicates would make deterministic planning ambiguous.

Fields

system_id: SystemID

The duplicated system identifier.

UnknownSystemId

An explicit scheduler ordering referenced a system ID that has not been registered with the scheduler.

Fields

system_id: SystemID

The missing system identifier.

SelfSystemOrdering

An explicit scheduler ordering made a system depend on itself.

Fields

system_id: SystemID

The self-dependent system identifier.

SchedulerInvariantViolation

Execution was aborted because the scheduler violated its declared access guarantees.

SchedulerCycle

The scheduler detected a dependency cycle in the combined (component-conflict + channel-ordering + explicit-ordering) partial order.

Common cycle shape: system A produces channel X and consumes channel Y; system B produces channel Y and consumes channel X. Break the cycle by removing one dependency, or restructure communication through ECS components / shared Arc<Environment> instead.

LockPoisoned

A synchronization primitive was poisoned (panic while held).

Fields

what: &'static str

Description of the poisoned lock.

GpuNotEnabled

GPU execution requested but crate was built without --features gpu.

GpuUnsupportedComponent

Component used by GPU system is not registered as GPU-safe.

Fields

component_id: ComponentID

component ID of the unsupported component.

name: &'static str

text name of the unsupported component.

GpuInitFailed

GPU init failed.

Fields

message: Cow<'static, str>

initialization failure reason.

GpuDispatchFailed

GPU dispatch failed.

Fields

message: Cow<'static, str>

dispatch failure reason.

GpuMissingBuffer

A required GPU buffer was missing during dispatch.

Fields

archetype_id: ArchetypeID

Archetype for which the GPU buffer was requested.

component_id: ComponentID

Component whose GPU buffer was missing.

access: GPUAccessMode

Intended GPU access mode for the missing buffer.

InternalExecutionError

Unsafe execution path was invoked incorrectly.

SystemRuntime(String)

A system’s runtime logic produced an error (e.g. a Python script failure). The contained string carries the formatted error message.

Trait Implementations

impl Clone for ExecutionError

fn clone(&self) -> ExecutionError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ExecutionError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ExecutionError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for ExecutionError

impl Error for ExecutionError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<ExecutionError> for ECSError

fn from(e: ExecutionError) -> Self

Converts to this type from the input type.

impl PartialEq for ExecutionError

fn eq(&self, other: &ExecutionError) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ExecutionError