Enum EngineError 

pub enum EngineError {
    MissingStore,
    MissingVisibilityStore,
    Load {
        reason: String,
    },
    UnenforceableContract {
        workflow_type: String,
        count: usize,
        detail: String,
    },
    UnknownVersion {
        workflow_type: String,
        version: ContentHash,
        loaded: String,
    },
    VersionPinned {
        workflow_type: String,
        version: ContentHash,
        pinned_by: PinHolder,
    },
    RouteActive {
        workflow_type: String,
        version: ContentHash,
    },
    ManifestMismatch {
        workflow_type: String,
        version: ContentHash,
        resident_digest: String,
        incoming_digest: String,
    },
    ConflictingEventPublisher,
    EventStreaming(PublishError),
    Store(StoreError),
    Durability(DurabilityError),
    Package(PackageError),
    ContractIdentity {
        workflow_type: String,
        source: ContractIdentityError,
    },
    NoQueueDeclaration {
        workflow_type: String,
        version: ContentHash,
        activities: String,
    },
    StartInputRefused {
        workflow_type: String,
        version: ContentHash,
        reason: String,
    },
    SignalRefused {
        workflow_id: WorkflowId,
        run_id: RunId,
        signal_name: String,
        version: ContentHash,
        reason: String,
    },
    Runtime {
        reason: String,
    },
    Gate3BifReplacementMissing {
        module: String,
        function: String,
        arity: u8,
    },
    CleanupExecutorPoisoned,
    CleanupExecutorShutdownTimedOut {
        timeout_millis: u128,
    },
    ProcessExitRegistryPoisoned,
    ProcessExitOwnershipPoisoned {
        process_id: u64,
    },
    ProcessExitStatePoisoned {
        process_id: u64,
    },
    ProcessExitSubscriptionUnavailable,
    ProcessExitDrainerSpawn {
        reason: String,
    },
    ProcessExitDrainerPoisoned,
    ProcessExitOutcomeMissingAfterEvent {
        process_id: u64,
    },
    ProcessExitEventStreamDisconnected,
    ProcessExitDrainerShutdownTimedOut {
        timeout_millis: u128,
    },
    ProcessExitDrainerPanicked,
    ProcessExitCallbackDispatcherPoisoned,
    ProcessExitCallbackDispatcherUnavailable,
    ProcessExitCallbackDispatcherShutdownTimedOut {
        timeout_millis: u128,
    },
    ProcessExitAlreadyTerminal {
        process_id: u64,
    },
    ActivityDeliveryPoisoned {
        process_id: u64,
    },
    RegistryPoisoned,
    CatalogPoisoned,
    InvalidState {
        reason: String,
    },
    ShuttingDown,
    WorkflowNotFound {
        workflow_type: String,
    },
    TerminalWriterUnavailable {
        workflow_id: String,
        run_id: String,
        holder: String,
    },
    TerminalWriterHeld {
        workflow_id: String,
        run_id: String,
    },
    EngineTaskEpochClosed {
        workflow_id: String,
        run_id: String,
    },
    RunIsRecoverable {
        workflow_id: String,
        run_id: String,
        version: String,
    },
    NoResidencyVerdict {
        workflow_id: String,
        run_id: String,
    },
    ScheduleNotFound {
        schedule_id: ScheduleId,
    },
    Schedule {
        reason: String,
    },
    NifRegistration {
        reason: String,
    },
    SignalRouter(SignalRouterError),
    Query(QueryError),
}

Errors returned by the embedded workflow engine.

Variants

MissingStore

The builder was asked to construct an engine without an event store.

MissingVisibilityStore

The builder was asked to construct an engine without a visibility store.

Load

A workflow package failed to load or validate for engine registration.

Fields

reason: String

Human-readable load failure reason.

UnenforceableContract

A package offered for deployment declares a contract the engine cannot enforce: at least one declared schema does not compile into a validator.

Refused at the door rather than admitted, because the alternative is silent: every admission boundary answers an uncompilable schema by letting the value through unchecked, so a package that reaches the catalog with one runs with that part of its declared contract switched off and only a log line to say so.

Fields

workflow_type: String

Logical workflow type of the refused package.

count: usize

How many declarations could not be compiled.

detail: String

Each unenforceable declaration, named, with the compiler’s reason.

UnknownVersion

A route or unload targeted a (workflow type, version) that is not loaded.

Fields

workflow_type: String

Logical workflow type requested by the caller.

version: ContentHash

Content-hash version requested by the caller.

loaded: String

Comma-separated loaded versions of the type, or none.

VersionPinned

An unload was refused because something still pins the version.

Fields

workflow_type: String

Logical workflow type targeted by the unload.

version: ContentHash

Content-hash version targeted by the unload.

pinned_by: PinHolder

What pins the version, naming the concrete holder.

RouteActive

An unload was refused because the version is route-active for its type.

Fields

workflow_type: String

Logical workflow type targeted by the unload.

version: ContentHash

Content-hash version targeted by the unload.

ManifestMismatch

An idempotent re-load presented the resident package identity with a different manifest. V4 binds beams and the durable execution contract, but not every packaging/admin field, so this remains the wrong-deploy tripwire: the resident version is retained and the archive is refused.

Fields

workflow_type: String

Logical workflow type targeted by the load.

version: ContentHash

Content-hash version shared by both archives.

resident_digest: String

Canonical digest of the resident manifest.

incoming_digest: String

Canonical digest of the incoming manifest.

ConflictingEventPublisher

The builder was given both event_streaming and an explicit event-publisher seam.

EventStreaming(PublishError)

Live event streaming setup failed.

Store(StoreError)

The configured event store returned an error.

Durability(DurabilityError)

The durability recorder or replay path returned an error.

Package(PackageError)

A .aion package operation returned an error.

ContractIdentity

The selected package identity predates the .v4 contract commitment.

Fields

workflow_type: String

Workflow type selected for the start.

source: ContractIdentityError

Typed migration refusal from the package identity boundary.

NoQueueDeclaration

The package names activities without a durable queue-scoped contract.

Fields

workflow_type: String

Workflow type selected for the start.

version: ContentHash

Exact .v4 package identity selected for the run.

activities: String

Stable comma-separated unscoped activity names.

StartInputRefused

A start’s input did not satisfy the declared input schema of the exact package identity the start resolved to.

Returned at the start boundary BEFORE any history is appended and before any process is spawned, so a refused start leaves no trace: the caller sees their own mistake at the moment they made it, with nothing to clean up.

Fields

workflow_type: String

Workflow type selected for the start.

version: ContentHash

Exact .v4 package identity the start resolved to.

reason: String

What did not match, naming every field that failed.

SignalRefused

A signal was refused at the boundary: its name is not declared by the target run’s package, or its payload did not satisfy the declared payload type.

Returned BEFORE anything is recorded and before the arrival can be consumed, so the target run’s history is unchanged and it stays parked on exactly the wait it was parked on. That ordering is the whole point: a signal decoded after being consumed destroys a durable run that a refusal merely inconveniences.

Fields

workflow_id: WorkflowId

Workflow execution the signal targeted.

run_id: RunId

Concrete run the signal targeted.

signal_name: String

Signal name the caller sent.

version: ContentHash

Exact .v4 package identity the target run is pinned to.

reason: String

Why the signal was refused — an undeclared name, or the fields of the payload that did not match the declared type.

Runtime

The embedded runtime returned an error.

Fields

reason: String

Human-readable runtime failure reason.

Gate3BifReplacementMissing

A Gate-3 BIF required for tracked local fun spawns was not registered.

Fields

module: String

Native module containing the required function.

function: String

Required native function.

arity: u8

Required native function arity.

CleanupExecutorPoisoned

The runtime-owned cleanup executor’s ownership state was poisoned.

CleanupExecutorShutdownTimedOut

The runtime cleanup worker did not stop within the configured bound.

Fields

timeout_millis: u128

Configured shutdown observation bound in milliseconds.

ProcessExitRegistryPoisoned

The process-exit registry lifecycle lock was poisoned.

ProcessExitOwnershipPoisoned

A process exit record’s installation/abort ownership gate was poisoned.

Fields

process_id: u64

Process whose monitor/abort ownership could not be serialized.

ProcessExitStatePoisoned

A process exit record’s fan-out state was poisoned.

Fields

process_id: u64

Process whose cached exit state could not be accessed.

ProcessExitSubscriptionUnavailable

The scheduler’s one exit-event subscription was already claimed.

ProcessExitDrainerSpawn

The singleton process-exit drainer could not be spawned.

Fields

reason: String

Operating-system thread creation failure.

ProcessExitDrainerPoisoned

The singleton process-exit drainer’s ownership lock was poisoned.

ProcessExitOutcomeMissingAfterEvent

beamr published an exit event without the promised durable outcome.

Fields

process_id: u64

Process named by the contract-breaking event.

ProcessExitEventStreamDisconnected

beamr disconnected its event publisher while the runtime still owned it.

ProcessExitDrainerShutdownTimedOut

The process-exit drainer did not stop within the configured bound.

Fields

timeout_millis: u128

Configured shutdown observation bound in milliseconds.

ProcessExitDrainerPanicked

The process-exit drainer thread panicked.

ProcessExitCallbackDispatcherPoisoned

The process-exit callback dispatcher’s ownership state was poisoned.

ProcessExitCallbackDispatcherUnavailable

The process-exit callback dispatcher had already stopped.

ProcessExitCallbackDispatcherShutdownTimedOut

The process-exit callback dispatcher did not stop within its configured bound.

Fields

timeout_millis: u128

Configured shutdown observation bound in milliseconds.

ProcessExitAlreadyTerminal

A retired process generation cannot accept another outcome consumer.

Fields

process_id: u64

Process generation whose heavyweight exit record was retired.

ActivityDeliveryPoisoned

A workflow’s activity-delivery synchronization lock was poisoned.

Fields

process_id: u64

Workflow process whose scoped delivery lock was poisoned.

RegistryPoisoned

The active workflow registry lock was poisoned.

CatalogPoisoned

The workflow catalog lock was poisoned.

InvalidState

A precondition on the target workflow’s current state was not met.

Raised by the reopen operation when the target run is not in a reopenable state: not terminal, terminal for a non-reopenable reason (Completed/TimedOut), or already Running. The reason names the actual status so callers and operators can see why the reopen was rejected. Maps to the INVALID_STATE wire code (gRPC FailedPrecondition / HTTP 409).

Fields

reason: String

Human-readable precondition-failure reason naming the actual status.

ShuttingDown

The engine is already shutting down and no new workflow starts are accepted.

WorkflowNotFound

No live, durable, or loaded workflow was found for the request.

Fields

workflow_type: String

Logical workflow type requested by the caller.

TerminalWriterUnavailable

A terminal-writer reservation could not be taken because the workflow already has a writer (#117(c)).

The extraordinary cancellation path exists only for a run that can never obtain a handle. A workflow that has one — or that another reservation is already writing — is not that case, and taking a second writer would break the single-writer invariant this refusal protects.

Fields

workflow_id: String

Workflow whose writer slot is occupied.

run_id: String

Run the refused reservation named.

holder: String

What holds the slot, in the operator’s terms.

TerminalWriterHeld

A handle could not be registered because a terminal-writer reservation holds this workflow’s writer slot (#117(c)).

The mirror of Self::TerminalWriterUnavailable, and transient by construction: a reservation lives only across one terminal transition.

Fields

workflow_id: String

Workflow whose writer slot is reserved.

run_id: String

Run holding the reservation.

EngineTaskEpochClosed

A terminal event was about to be appended after the engine-task epoch had already closed.

Raised at the append boundary itself, which is the only instant at which the hazard it guards is real. The engine that owned this run has been shut down or released, so this process is no longer that workflow’s single writer (invariant 3). Appending here risks two writers.

This is not only the successor case

The obvious reading — a successor engine is already recovering the same history — is the eventual case, not the whole of it. Engine::shutdown closes the epoch as its FIRST act and only stops admitting process-exit callbacks several steps later, so this error is also raised for runs that exit during this engine’s own graceful teardown, while no successor exists yet. Saying “a successor may already be recovering” would tell an operator reading the message during a clean shutdown to go looking for a second node that is not there.

Deliberately not transient: no later attempt re-opens a closed epoch. In both cases the run stays Running and a startup sweep — the successor’s, or this node’s own on restart — re-installs a monitor, which is the mechanism that actually repairs it.

Fields

workflow_id: String

Workflow whose terminal event was refused.

run_id: String

Run whose terminal event was refused.

RunIsRecoverable

The extraordinary cancellation path was asked for a run whose pinned package resolves right now, so the run is recoverable (#117(c)).

Measured at the moment of the request, never cited from an earlier boot’s verdict: a redeploy between then and now is exactly the remedy that makes the ordinary path work again, and the ordinary path must be used when it does.

Fields

workflow_id: String

Workflow the request named.

run_id: String

Run the request named.

version: String

The pinned package version that resolved.

NoResidencyVerdict

A run holds no handle, cannot obtain one, and this engine has no recorded reason why (#117(c)).

Distinct from Self::WorkflowNotFound on purpose: the run EXISTS and its history is readable. What is absent is a verdict from this process’s startup recovery, so the extraordinary cancellation path — which must cite that verdict — has nothing to cite.

Fields

workflow_id: String

Workflow the request named.

run_id: String

Run the request named.

ScheduleNotFound

No durable schedule was found for the request.

Fields

schedule_id: ScheduleId

Schedule identifier requested by the caller.

Schedule

Schedule trigger, projection, or evaluator side effect failed.

Fields

reason: String

Human-readable schedule failure reason.

NifRegistration

Native implemented function registration failed.

Fields

reason: String

Human-readable native implemented function registration failure reason.

SignalRouter(SignalRouterError)

Signal routing failed after the target was resolved.

Query(QueryError)

Live workflow query dispatch failed after the target was resolved.

Trait Implementations

impl Debug for EngineError

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

Formats the value using the given formatter.

impl Display for EngineError

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

Formats the value using the given formatter.

impl Error for EngineError

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<DurabilityError> for EngineError

fn from(source: DurabilityError) -> Self

Converts to this type from the input type.

impl From<PackageError> for EngineError

fn from(source: PackageError) -> Self

Converts to this type from the input type.

impl From<PublishError> for EngineError

fn from(source: PublishError) -> Self

Converts to this type from the input type.

impl From<QueryError> for EngineError

fn from(source: QueryError) -> Self

Converts to this type from the input type.

impl From<ScheduleError> for EngineError

fn from(error: ScheduleError) -> Self

Converts to this type from the input type.

impl From<ScheduleEvaluatorError> for EngineError

fn from(error: ScheduleEvaluatorError) -> Self

Converts to this type from the input type.

impl From<SignalRouterError> for EngineError

fn from(source: SignalRouterError) -> Self

Converts to this type from the input type.

impl From<StoreError> for EngineError

fn from(source: StoreError) -> Self

Converts to this type from the input type.