Enum ServerError 

pub enum ServerError {
    Config {
        message: String,
    },
    UnsafeDataRootAncestor {
        data_root: PathBuf,
        component: PathBuf,
        reason: String,
    },
    TransportBind {
        transport: &'static str,
        address: SocketAddr,
        message: String,
    },
    Transport {
        transport: &'static str,
        message: String,
    },
    SignalListener {
        listener: &'static str,
        message: String,
    },
    DeathNote {
        message: String,
    },
    PidFile {
        message: String,
    },
    HomeAlreadyClaimed {
        refusal: Box<HomeAlreadyClaimed>,
    },
    Incarnation {
        message: String,
    },
    Namespace {
        message: String,
    },
    EngineCall {
        source: EngineError,
    },
    StoreBackend {
        source: StoreError,
    },
    Stream {
        failure: StreamFailure,
    },
    WorkerDispatch {
        namespace: String,
        activity_type: String,
        reason: String,
    },
    WorkerConnectionLost {
        channel: String,
        detail: String,
    },
    WorkerBusy {
        channel: String,
        detail: String,
    },
    WorkerDispatchUnservable {
        channel: String,
        detail: String,
    },
    PendingActivityCollision {
        workflow_id: WorkflowId,
        activity_id: ActivityId,
        held_attempt: u32,
        incoming_attempt: u32,
    },
    ActivityCompletionRejected {
        workflow_id: WorkflowId,
        activity_id: ActivityId,
        reason: CompletionRejectionReason,
    },
    DeclaredAttemptCollision {
        workflow_id: WorkflowId,
        activity_id: ActivityId,
        attempt: u32,
    },
    DrainingRefusedDeclaredAttempt {
        workflow_id: WorkflowId,
        activity_id: ActivityId,
        attempt: u32,
    },
    LockPoisoned {
        resource: &'static str,
    },
    Wire {
        wire: WireError,
    },
}

Server-library error taxonomy.

Variants

Config

Operator configuration could not be loaded or validated.

Fields

message: String

Redacted, operator-facing failure message.

UnsafeDataRootAncestor

A path-ambient store backend was configured beneath a renameable directory.

Fields

data_root: PathBuf

Descriptor-resolved data root that the backend would use by pathname.

component: PathBuf

First unsafe component in the resolved root’s ancestor chain.

reason: String

Ownership, mode, or inspection failure that made the component unsafe.

TransportBind

A transport listener could not bind or start.

Fields

transport: &'static str

Transport name.

address: SocketAddr

Configured listener address.

message: String

Redacted, operator-facing failure message.

Transport

A running transport task aborted: it panicked or was cancelled.

Fields

transport: &'static str

Transport name.

message: String

Redacted, operator-facing failure message.

SignalListener

A termination-signal listener could not be installed or failed.

Fields

listener: &'static str

Listener name (SIGTERM, SIGINT, or the portable fallback).

message: String

Redacted, operator-facing failure message.

DeathNote

The death note — the durable record of what killed the process — could not be armed at boot.

Fields

message: String

Redacted, operator-facing failure message.

PidFile

The pid file or a control-verb record could not be written or read.

Fields

message: String

Redacted, operator-facing failure message.

HomeAlreadyClaimed

A LIVE server incarnation already holds this Aion home on addresses that collide with the ones this boot intends to bind. Refusing is the whole point: two servers on one home do not share it — the second blocks silently inside the store’s writer lock — so this is an operator-facing refusal (exit 2), not a crash.

Fields

refusal: Box<HomeAlreadyClaimed>

The refusal, carrying the live holder’s whole record so a caller can render whatever the operator needs. Boxed to keep ServerError small: every other variant is a handful of words.

Incarnation

This process’s own incarnation identity (process-table start instant, executable path, binary hash) could not be read.

Fields

message: String

Redacted, operator-facing failure message.

Namespace

Namespace validation or authorization failed.

Fields

message: String

Redacted namespace failure message.

EngineCall

Engine call failed.

Fields

source: EngineError

Typed engine error returned by the embedded engine.

StoreBackend

Store backend call failed before an engine handle was available.

Fields

source: StoreError

Typed store error returned by the configured backend.

Stream

Streaming failure.

Fields

failure: StreamFailure

Stream failure class.

WorkerDispatch

A scheduled activity could not be pushed to a worker.

Fields

namespace: String

Namespace scoped before dispatch.

activity_type: String

Activity type requested by the engine.

reason: String

Redacted dispatch failure reason.

WorkerConnectionLost

The worker connection chosen for a dispatch was lost mid-flight: the connection was already gone at push time, or it closed before the worker sent its correlated push reply.

This is DISTINCT from Self::WorkerDispatch: a WorkerDispatch covers a genuine reply timeout (the worker is alive but slow), a no-worker-available selection failure, or any other dispatch fault, all of which keep the outbox’s normal exponential backoff. A WorkerConnectionLost instead means the chosen worker is gone (and has already been deregistered by liminal’s on_worker_unregistered), so the row can be re-armed for IMMEDIATE re-claim to fail over to a live worker without waiting out the backoff. The outbox dispatcher keys its fast-failover decision on this variant.

Fields

channel: String

Row-derived dispatch channel for operator diagnostics.

detail: String

Redacted, operator-facing description of how the connection was lost.

WorkerBusy

The worker connection chosen for a dispatch refused admission because it already holds its pending-push cap — the worker is ALIVE and WORKING, its connection is simply full of held dispatches.

DISTINCT from both Self::WorkerDispatch (which consumes a retry attempt on backoff) and Self::WorkerConnectionLost (immediate attempt-consuming failover): a busy worker is neither slow to reply nor gone, so the outbox re-arms the row ATTEMPT-NEUTRALLY after a short backoff — capacity pressure must never spend the retry budget that prices genuine delivery failures, and must never dead-letter work.

Fields

channel: String

Row-derived dispatch channel for operator diagnostics.

detail: String

Redacted, operator-facing description of the admission refusal.

WorkerDispatchUnservable

The dispatch can never be delivered on this worker connection at this bound, on this attempt or any later one: liminal proved the encoded dispatch frame is larger than the connection’s WHOLE outbound buffer (liminal_server::ServerError::PushFrameExceedsOutboundCapacity), so no amount of draining, waiting or failover to an identically-bounded worker can carry it.

DISTINCT from all three dispatch-failure classes above, and the distinction is the fix: Self::WorkerConnectionLost fails over immediately, Self::WorkerBusy parks attempt-neutrally, and Self::WorkerDispatch retries on backoff. Each of those is the right answer to a fault that can clear. This one cannot clear, and every retry of it writes another lease and another copy of the oversize input into durable history for a step that never ran (measured: 846 leases, 5.93 MiB, one activity). Both dispatch paths therefore settle it TERMINALLY on the first observation: the outbox dead-letters the row, the engine-seam bridge reports a terminal: outcome. The detail names the frame’s size, the bound, and the operator key that sets the bound.

Fields

channel: String

Row-derived dispatch channel for operator diagnostics.

detail: String

Operator-facing description naming the frame size, the bound and the key that sets it.

PendingActivityCollision

A second dispatcher tried to install a responder for an execution site whose prior attempt is still held live, and the incoming attempt does not supersede the holder.

A HIGHER attempt never reaches this error: it takes the site over (aion#195) — the fence already superseded the holder’s tokens when the higher attempt was issued, so the holder is a corpse whose completion would be refused anyway, and refusing the live retry on its account killed healthy runs. Only a same-or-lower attempt — a genuine double dispatch of work that may still be executing — is refused here.

Fields

workflow_id: WorkflowId

Workflow whose responder slot is already occupied.

activity_id: ActivityId

Activity site whose responder slot is already occupied.

held_attempt: u32

Attempt the live holder was dispatched at.

incoming_attempt: u32

Attempt the refused dispatch arrived at.

ActivityCompletionRejected

A worker result did not prove ownership of the current execution generation and was refused before reaching workflow state.

Fields

workflow_id: WorkflowId

Workflow named by the submitted completion.

activity_id: ActivityId

Activity site named by the submitted completion.

reason: CompletionRejectionReason

Typed reason the completion token did not authorize this write.

DeclaredAttemptCollision

A second server-executed declared body was started for an execution site whose prior attempt is still running here.

Distinct from Self::PendingActivityCollision, which is about the responder slot a dispatch installs: this is about the PROCESS. The registry that makes a running declared command cancellable holds one cancellation handle per attempt, so admitting a second execution would replace the first command’s handle — and a replaced handle is a command running on the operator’s machine that nothing can stop. Refusing the second is the only outcome that leaves both attempts accounted for.

Fields

workflow_id: WorkflowId

Workflow whose declared body is already executing.

activity_id: ActivityId

Activity site whose declared body is already executing.

attempt: u32

Attempt whose declared body is already executing.

DrainingRefusedDeclaredAttempt

A draining server refused to start a declared command.

The drain latch is the promise aion server stop makes to the operator: no new work starts after the stop is requested. A declared body executes at the server itself — no worker gate can refuse it — so the registration that admits it to the cancel path is also the door the drain closes. The dispatcher maps this refusal to the park sentinel, exactly like a worker dispatch parked mid-drain: nothing is recorded, and the next boot re-dispatches the attempt.

Fields

workflow_id: WorkflowId

Workflow whose declared body was refused.

activity_id: ActivityId

Activity site whose declared body was refused.

attempt: u32

Attempt whose declared body was refused.

LockPoisoned

A lock was poisoned and the protected state cannot be trusted.

Fields

resource: &'static str

Protected resource name.

Wire

A failure already translated into the public wire taxonomy.

Fields

wire: WireError

Stable wire error.

Implementations

impl ServerError

pub fn to_wire_error(&self) -> WireError

Convert a server error that crosses a transport boundary into the stable public wire taxonomy.

pub const fn is_config(&self) -> bool

Return true when this is an operator configuration failure.

pub fn namespace_denied(message: impl Into<String>) -> Self

Construct a namespace-denied error without embedding authorization logic.

pub fn placement_admission_denied( namespace: &str, worker_node: Option<&str>, required: &BTreeSet<String>, ) -> Self

Construct the loud, whole-registration rejection when a worker’s advertised node violates a Pinned{L} namespace’s placement (Control-Plane Phase 2, P2-I1). Names the offending namespace, the worker’s advertised node (or “none”), and the required label set, so the operator sees exactly why the registration was refused. Carried on the namespace-denied wire code — a registration refused on isolation grounds is a namespace-authorization failure, not a transient dispatch error.

pub fn deploy_denied(message: impl Into<String>) -> Self

Construct a deploy-authorization denial carried on the dedicated deploy_denied wire code (deploy is not a namespace operation).

pub fn grant_denied(message: impl Into<String>) -> Self

Construct a grant-authorization denial carried on the dedicated grant_denied wire code.

Separate from Self::deploy_denied on purpose: deploy_denied names the deploy surface, so spelling it for a caller refused on some other grant word would send that caller — and the operator reading the audit line — to a surface the request never touched. Built by crate::namespace::grants::require_grant, which fills in the word and the knob that carries it.

pub const fn lagged_stream() -> Self

Construct a lagged-stream error.

pub fn worker_dispatch( namespace: impl Into<String>, activity_type: impl Into<String>, reason: impl Into<String>, ) -> Self

Construct a worker-dispatch error.

pub fn worker_connection_lost( channel: impl Into<String>, detail: impl Into<String>, ) -> Self

Construct a worker-connection-lost error for a dispatch whose chosen worker connection was gone at push time or closed before replying.

pub fn worker_dispatch_unservable( channel: impl Into<String>, detail: impl Into<String>, ) -> Self

Construct an unservable-dispatch error for a frame liminal proved larger than the worker connection’s whole outbound buffer.

pub const fn is_worker_connection_lost(&self) -> bool

Return true when this is a lost-worker-connection dispatch failure.

The outbox dispatcher keys its fast cross-node failover on this: a lost connection means the worker is gone (already deregistered), so the row is re-armed for immediate re-claim instead of waiting out the retry backoff.

pub fn worker_busy( channel: impl Into<String>, detail: impl Into<String>, ) -> Self

Construct a worker-busy error for a dispatch refused at push admission because the worker’s connection already holds its pending-push cap.

pub const fn is_worker_busy(&self) -> bool

Return true when this is a busy-worker admission refusal.

The outbox dispatcher keys its ATTEMPT-NEUTRAL re-arm on this: a full connection means the worker is alive and holding earlier dispatches, so the row waits for capacity without spending the retry budget that prices genuine delivery failures.

pub const fn is_worker_dispatch_unservable(&self) -> bool

Return true when this dispatch can never be delivered on its connection at the configured outbound bound, so no retry of it may ever be scheduled.

Both dispatch paths key their terminal settlement on this: the outbox dead-letters the row on the first observation, and the engine-seam bridge reports a non-retryable outcome.

pub const fn lock_poisoned(resource: &'static str) -> Self

Construct a lock-poison error at the lock boundary.

impl ServerError

pub fn trace_fields(&self) -> ErrorTraceFields<'_>

Return stable typed fields for structured error logging.

Trait Implementations

impl Debug for ServerError

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

Formats the value using the given formatter.

impl Display for ServerError

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

Formats the value using the given formatter.

impl Error for ServerError

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

fn from(source: EngineError) -> Self

Converts to this type from the input type.

impl From<StoreError> for ServerError

fn from(source: StoreError) -> Self

Converts to this type from the input type.

impl From<WireError> for ServerError

fn from(wire: WireError) -> Self

Converts to this type from the input type.