aion/error

Typed error taxonomy for Aion workflow authors.

The aion_flow package models failure as data. Public fallible functions return typed Result errors; library code must not panic, call todo, or use assertions as control flow. Activity failures, decode failures, engine lifecycle failures, non-determinism, and unknown live-interaction names are all represented by the types in this module.

Types

ActivityError

</>

An activity dispatch failure returned through workflow.run.

Retryable and Terminal are the Gleam mirror of aion-core’s retryable / terminal activity-error classification (aion-core C21). The engine retries Retryable failures according to the activity’s explicit RetryPolicy until its attempts are exhausted, and fails immediately for Terminal failures.

Engine-originated failures that can occur while dispatching or decoding an activity result are also represented here so workflow.run(Activity(i, o)) remains a single typed Result(o, ActivityError) boundary. Decode failures preserve the typed codec error and are never swallowed or raised as panics.

details carries structured detail data encoded by the author-facing codec layer. The SDK keeps it as an opaque string here so activity authors do not depend on engine payload internals.

pub type ActivityError {
  Retryable(message: String, details: String)
  Terminal(message: String, details: String)
  ActivityDecodeFailed(codec.DecodeError)
  ActivityTimedOut(TimeoutError)
  ActivityCancelled(CancellationError)
  ActivityNonDeterministic(NonDeterminismError)
  ActivityEngineFailure(message: String)
}

Constructors

Retryable(message: String, details: String)

Terminal(message: String, details: String)

```
ActivityDecodeFailed(codec.DecodeError)
```
```
ActivityTimedOut(TimeoutError)
```
```
ActivityCancelled(CancellationError)
```

ActivityNonDeterministic(NonDeterminismError)

```
ActivityEngineFailure(message: String)
```

BoundaryDecodeError

</>

A boundary decode failure for workflow primitives.

The wrapped codec.DecodeError preserves the typed decode reason and path produced by AF-002 codecs. Decode failures are returned as data and are never swallowed or raised as panics.

pub type BoundaryDecodeError {
  DecodeFailed(codec.DecodeError)
}

Constructors

```
DecodeFailed(codec.DecodeError)
```

CancellationError

</>

A cancellation reported by the engine lifecycle.

Cancellation originates from the engine’s workflow or command lifecycle and remains separate from author-returned activity decisions.

pub type CancellationError {
  Cancelled(reason: String)
}

Constructors

```
Cancelled(reason: String)
```

ChildError

</>

A child-workflow await failure.

A completed child returns Ok(output). A child workflow failure returns ChildWorkflowFailed(workflow_error), preserving the child workflow’s typed error. Decode, cancellation, non-determinism, and engine failures are separate typed variants so boundary failures are never swallowed or raised as panics.

pub type ChildError(workflow_error) {
  ChildWorkflowFailed(workflow_error)
  ChildOutputDecodeFailed(codec.DecodeError)
  ChildErrorDecodeFailed(codec.DecodeError)
  ChildCancelled(CancellationError)
  ChildNonDeterministic(NonDeterminismError)
  ChildEngineFailure(message: String)
}

Constructors

```
ChildWorkflowFailed(workflow_error)
```

ChildOutputDecodeFailed(codec.DecodeError)

ChildErrorDecodeFailed(codec.DecodeError)

```
ChildCancelled(CancellationError)
```

ChildNonDeterministic(NonDeterminismError)

```
ChildEngineFailure(message: String)
```

EngineError

</>

A generic engine-originated primitive failure.

Deterministic primitives such as workflow.now and workflow.random are bound to AD through the FFI layer. If the engine reports an unavailable context or malformed deterministic value, the SDK returns this data rather than panicking.

pub type EngineError {
  EngineFailure(message: String)
}

Constructors

```
EngineFailure(message: String)
```

NonDeterminismError

</>

A deterministic replay violation reported by AD.

This corresponds to AD’s NonDeterminismError: the workflow command stream produced during replay did not match recorded history. Workflow code handles it as an engine-originated failure, never as an author retry/terminal decision.

pub type NonDeterminismError {
  NonDeterminismViolation(message: String)
}

Constructors

NonDeterminismViolation(message: String)

QueryError

</>

A query failure.

Future query primitives use this type to distinguish malformed query payloads, unknown query names, cancellation, and deterministic replay violations. Queries do not record workflow events.

pub type QueryError {
  QueryDecodeFailed(codec.DecodeError)
  UnknownQuery(name: String)
  QueryCancelled(CancellationError)
  QueryNonDeterministic(NonDeterminismError)
  QueryEngineFailure(message: String)
}

Constructors

```
QueryDecodeFailed(codec.DecodeError)
```
```
UnknownQuery(name: String)
```
```
QueryCancelled(CancellationError)
```

QueryNonDeterministic(NonDeterminismError)

```
QueryEngineFailure(message: String)
```

ReceiveError

</>

A signal receive failure.

Future signal primitives use this type to distinguish malformed payloads, unknown signal names, cancellation, and deterministic replay violations.

pub type ReceiveError {
  ReceiveDecodeFailed(codec.DecodeError)
  UnknownSignal(name: String)
  ReceiveCancelled(CancellationError)
  ReceiveNonDeterministic(NonDeterminismError)
  ReceiveEngineFailure(message: String)
}

Constructors

```
ReceiveDecodeFailed(codec.DecodeError)
```
```
UnknownSignal(name: String)
```
```
ReceiveCancelled(CancellationError)
```

ReceiveNonDeterministic(NonDeterminismError)

```
ReceiveEngineFailure(message: String)
```

TimeoutError

</>

A timeout reported by the engine lifecycle.

Later workflow primitives such as with_timeout, timers, and activity timeout handling use this type when the engine decides that a deadline has expired. This is separate from author retry/terminal decisions because authors must not classify an engine timeout as an activity retry decision.

pub type TimeoutError {
  TimedOut(message: String)
}

Constructors

```
TimedOut(message: String)
```

TimeoutResultError

</>

A timeout wrapper for primitives that can either finish or expire.

TimedOutError is reserved for genuine deadline expirations; an engine fault while establishing or settling the timeout scope surfaces as TimeoutEngineFailure so callers never mistake an infrastructure error for a timeout.

pub type TimeoutResultError(error) {
  TimedOutError(TimeoutError)
  InnerError(error)
  TimeoutEngineFailure(message: String)
}

Constructors

```
TimedOutError(TimeoutError)
```
```
InnerError(error)
```
```
TimeoutEngineFailure(message: String)
```

WorkflowError

</>

A workflow lifecycle primitive failure.

pub type WorkflowError {
  WorkflowEngineFailure(message: String)
}

Constructors

```
WorkflowEngineFailure(message: String)
```

Values

retryable

</>

pub fn retryable(message: String) -> ActivityError

Construct a retryable activity failure with no detail payload.

retryable_with_details

</>

pub fn retryable_with_details(
  message: String,
  details: String,
) -> ActivityError

Construct a retryable activity failure with an encoded detail payload.

terminal

</>

pub fn terminal(message: String) -> ActivityError

Construct a terminal activity failure with no detail payload.

terminal_with_details

</>

pub fn terminal_with_details(
  message: String,
  details: String,
) -> ActivityError

Construct a terminal activity failure with an encoded detail payload.