Skip to content

duron.errors module

Application failures are recorded as outcomes and delivered as ApplicationError. Runtime failures describe problems with definitions, history, ownership, or scheduling. Cancellation is handled separately; let asyncio.CancelledError propagate so the runtime can complete cleanup.

Application failures

Effects record ordinary exceptions as outcomes. Every persisted application failure is delivered as ApplicationError, both during the first execution and on replay. Uncaught workflow failures observed through run.result() use the same type. Cancellation remains separate.

ApplicationError exposes type_name, message, optional JSON details, and cause (also available as Python's __cause__). For ordinary exceptions, type_name is the module-qualified class name, such as builtins:ValueError. Duron stores a bounded explicit cause chain; it does not reconstruct exception classes, constructor arguments, or arbitrary attributes.

Raise ApplicationError directly to supply a stable application error code and structured details. Re-raising it preserves its type name and details across further durable boundaries:

from duron.errors import ApplicationError

# Inside an effect:
raise ApplicationError(
    "payment_rejected", "Payment was declined", details={"code": 409}
)

For richer details, explicitly call an application codec's encode_json before raising and decode_json with a known schema when catching the error. Duron persists details as finite JSON; it never sends exception objects to the codec.

Runtime failures

Submission and run lifecycle

Error Meaning and response
SubmissionConflictError A run ID identifies a different immutable invocation.
ContractMismatchError A reference differs from the persisted or registered contract.
RunCancelledError The workflow acknowledged durable cancellation.
RunFailedError No workflow outcome is available because the run is blocked or scheduling failed. kind is a FailureKind, including INTERRUPTED_EFFECT for an effect without an outcome.
RunNotFoundError An operation selected an absent run.

Definitions and history

Error Meaning and response
HistoryMismatchError The selected definition, inputs, or operation sequence disagrees with history. Use compatible code for that run, or start a new run.
InterruptedEffectError Replay found an effect call without a final outcome. The scheduler marks the run BLOCKED and will not invoke the effect again.
WorkflowDefinitionError The definition or port interface is invalid, or input consumers overlap with an interruptible scope.
CorruptLogError A persisted record cannot be decoded or validated. Inspect the underlying history and its reported offset.

Ports and messages

Error Meaning and response
PortClosedError A workflow input is closed and drained, or an effect output is closed. Host sends to closed inputs or terminal runs are discarded asynchronously.
Interrupted An interruptible scope consumed one input; value contains its payload.
ChannelClosedError A scoped effect channel is closed. An uncaught instance in an effect becomes an application failure.
PostConflictError A delivery ID or posting key conflicts with existing content, or an append batch mixes existing and new IDs.

Storage and execution ownership

Error Meaning and response
StorageError A storage operation failed, or another scheduler or store owns the database file.
ClaimLostError The write claim no longer belongs to this owner. Stop using the stale owner.
ClaimBusyError Another owner holds the claim. Wait for release.
RunUnavailableError The effect's run owner is no longer accepting operations.
InvalidHandleError An endpoint has an invalid identity, direction, type, or owner.
InvalidExecutionRequestError An executor request does not match the registered call.
InvalidPostError A posting key, action, or payload is invalid.
ExecutionCompletedError A mutation was attempted after the effect completed.

DuronError groups Duron-specific conditions. Invalid arguments may also raise standard TypeError or ValueError; cancellation uses asyncio.CancelledError. Ownership and history errors propagate as runtime failures.

Public error hierarchy for Duron.

Duron-specific conditions have dedicated classes for type-based handling. The intermediate WorkflowError and StorageError bases group related conditions. Invalid arguments can also raise standard Python exceptions.

JSONValue module-attribute

JSONValue: TypeAlias

Recursive type representing any valid JSON value.

__all__ module-attribute

__all__

ApplicationError

ApplicationError(
    type_name: str,
    message: str,
    *,
    details: JSONValue = None,
    cause: ApplicationError | None = None,
)

A persisted application failure from an effect or workflow.

details contains optional JSON data. Use an application codec explicitly to encode and decode richer details with a known schema. Original exception classes and constructor arguments are never reconstructed.

cause property

cause: BaseException | None

The explicit cause, also available through Python's __cause__.

details instance-attribute

details: JSONValue

message instance-attribute

message

type_name instance-attribute

type_name

ChannelClosedError

An explicit effect stream or signal channel is permanently closed.

ClaimBusyError

Another owner holds the history claim.

ClaimLostError

The storage claim was lost while appending to the run.

ContractMismatchError

A workflow reference does not match the persisted or registered contract.

CorruptLogError

CorruptLogError(offset: int, message: str)

Persisted log data cannot be decoded or validated.

offset instance-attribute

offset

DefaultCodec

Encode finite JSON values and return decoded values unchanged.

Supports None, booleans, numbers, strings, lists, and dictionaries with string keys. Annotations do not trigger type validation or reconstruction. Use a custom Codec for other Python types.

decode_json staticmethod

decode_json(
    encoded: JSONValue, _expected_type: TypeHint[_T]
) -> _T

encode_json staticmethod

encode_json(
    result: object, _annotated_type: TypeHint[object]
) -> JSONValue

DuronError

Base class for Duron-specific errors.

ExecutionCompletedError

A new mutation was attempted after final execution completion.

FailureKind

Why the scheduler stopped running a job without a workflow outcome.

CONTRACT_MISMATCH class-attribute instance-attribute

CONTRACT_MISMATCH

CORRUPT_HISTORY class-attribute instance-attribute

CORRUPT_HISTORY

HISTORY_MISMATCH class-attribute instance-attribute

HISTORY_MISMATCH

INFRASTRUCTURE class-attribute instance-attribute

INFRASTRUCTURE

INTERRUPTED_EFFECT class-attribute instance-attribute

INTERRUPTED_EFFECT

INVALID class-attribute instance-attribute

INVALID

UNAVAILABLE class-attribute instance-attribute

UNAVAILABLE

HistoryMismatchError

HistoryMismatchError(
    message: str,
    *,
    expected: object | None = None,
    actual: object | None = None,
)

A replay diverged from the recorded history.

The structured expected and actual fields name what diverged.

actual instance-attribute

actual

expected instance-attribute

expected

Interrupted

Interrupted(value: object)

A signal interrupted an interruptible block.

Attributes:

  • value –

    The payload sent with the signal that caused the interrupt.

value instance-attribute

value

InterruptedEffectError

InterruptedEffectError(operation_id: str)

A committed effect call has no final outcome and cannot be dispatched again.

operation_id instance-attribute

operation_id

InvalidExecutionRequestError

A worker request does not match its registered execution schema.

InvalidHandleError

A handle's identity, direction, type, or ownership is invalid.

InvalidPostError

A posting key, action, or payload is malformed.

PortClosedError

An input is closed for delivery, or closed and drained for receiving.

PostConflictError

A delivery ID, append batch, or posting key was reused with new content.

RunCancelledError

The durable workflow acknowledged cancellation.

RunFailedError

RunFailedError(message: str, kind: FailureKind)

No workflow outcome is available because the run is blocked or failed.

kind classifies the failure. INFRASTRUCTURE means the retry budget was exhausted; INVALID means a deterministic input or codec failure. A blocked run may resume when its implementation becomes available, but an interrupted effect is never invoked again.

kind instance-attribute

kind

RunNotFoundError

The selected persisted run does not exist.

RunUnavailableError

The run has no active owner accepting executor operations.

StorageError

Category base for storage and ownership failures.

SubmissionConflictError

A run ID already identifies a different immutable invocation.

WorkflowDefinitionError

A workflow or effect was declared or invoked incorrectly.

WorkflowError

Category base for workflow lifecycle and definition errors.