Errors

The exception hierarchy.

Every error explains itself. Following the project's Odin convention, a message names the context, the cause and a Hint: with the corrective action -- and the hint text comes from the native library, which reads the core's own explanation table. This package deliberately keeps no second copy of that text, because a duplicate is a copy that can drift.

PaxodinError

Bases: Exception

Base class for every error this package raises.

Every error renders in the same three-part shape the Odin core uses for its own, so a Python traceback reads like an Odin diagnostic::

-- NOT LEADER ------------------------------------------------------------------

This node has not completed phase one for its current ballot.
  leader = 2
Hint: Route to current_leader() or wait for a successful campaign.

The title names the situation, the cause says what happened with the values that matter, and the hint says what to do about it. An error never only states what failed. Hint text for a protocol error comes from the core's own table; this package keeps no copy that could drift.

Where a standard exception already means the right thing, the subclass inherits it too: a CommitTimeout is a TimeoutError, a ValueTooLarge is a ValueError, a StorageError is an OSError. Code that already handles the builtin keeps working; code that wants the detail asks for it.

Attributes:

Name	Type	Description
code	int	The stable status code, usable in logs and comparisons.
title	str	The banner text.
message		A one-sentence statement of what went wrong.
hint		The corrective action, never an apology.
context		Structured detail a caller can act on programmatically.

render

render() -> str

Render the Elm-style block: banner, cause, values, hint.

Returns:

Type	Description
str	The multi-line text str(exc) returns.

UsageError

Bases: PaxodinError

The caller used the API in a way that cannot be right.

InvalidArgument

Bases: UsageError, ValueError

An argument is outside the range this profile accepts.

ValueTooLarge

Bases: UsageError, ValueError

The command exceeds the compiled profile. No proposal was admitted.

UnsupportedKind

Bases: UsageError, ValueError

An enum tag is not one this ABI version defines.

UnsupportedCapability

Bases: UsageError

This build omits the feature. A capability ships only with its tests.

HandleClosed

Bases: UsageError, RuntimeError

The node is closed. A closed handle is never reopened.

ForkedHandle

Bases: UsageError

A native handle does not survive fork().

ReentrantCall

Bases: UsageError, RuntimeError

An adapter called back into the node that is driving it.

BatchError

Bases: PaxodinError

The pending-batch contract was not followed.

BatchPending

Bases: BatchError

A previous batch has not been discharged, so no transition may begin.

NoBatch

Bases: BatchError

There is no pending batch on this node.

StaleToken

Bases: BatchError

This token names a batch a later transition superseded.

ForeignToken

Bases: BatchError

This token belongs to another handle, or one since closed.

BatchFinished

Bases: BatchError

The batch was released; its native effects are gone.

WritesUnconfirmed

Bases: BatchError

Outputs were read, or the batch released, before its writes were durable.

AbandonedBatch

Bases: WritesUnconfirmed

A batch was left holding writes that were never confirmed durable.

The records were handed out but never acknowledged, so the node cannot tell which of them reached stable storage. Resuming would risk acting on a promise or a vote that a crash could revert.

WritesNotCopied

Bases: BatchError

Confirmation was requested for records the host never received.

ReplayActive

Bases: BatchError

This node is replaying a journal; transitions are not yet legal.

ReplayNotActive

Bases: BatchError

This node is live; replay applies only to one opened for it.

ProtocolError

Bases: PaxodinError

The core refused the operation. The node is intact.

NotLeader

Bases: ProtocolError

This participant is a follower; no forwarding is performed.

LeaderCatchingUp

Bases: ProtocolError

The leader has not yet delivered every inherited slot.

WindowFull

Bases: ProtocolError

The window cannot advance until released entries are durably consumed.

LogSealed

Bases: ProtocolError

A stop sign is pending or decided; this configuration takes no more.

ConfigurationMismatch

Bases: ProtocolError

The envelope belongs to another configuration. Nothing changed.

Trimmed

Bases: ProtocolError

The requested slots fell below the memory floor; read retained history.

CampaignDisabled

Bases: ProtocolError

This voter is configured never to start elections.

NativeError

Bases: PaxodinError

A native failure with no more specific class.

OutOfMemory

Bases: NativeError

The bridge could not allocate a node or its replay scratch.

Poisoned

Bases: NativeError

An invariant failed; the node is unusable rather than falsely recovered.

ProposalLost

Bases: ProtocolError

A different value was decided in the slot this command was admitted to.

In single-leader mode there is no resubmission. If the leader loses its ballot after admitting a command, recovery can choose another value for that slot and the command is simply dropped. Reporting success here would be a lie, so the mismatch is raised instead.

InvalidTimeout

Bases: UsageError, ValueError

A timeout that cannot mean anything was supplied.

A negative, NaN or infinite duration is rejected before it reaches native code, where it would otherwise become an unbounded wait.

CommitTimeout

Bases: ProtocolError, TimeoutError

The wait ended. This did not cancel anything.

A timeout is not a rejection: peers may choose the value moments later. admitted reports whether the command entered a slot at all.

StorageError

Bases: PaxodinError, OSError

Progress stopped with persistence uncertain.

Reopen and replay the journal rather than guessing which writes landed.

TransportError

Bases: PaxodinError, OSError

An adapter could not move a frame. Retransmission tolerates duplicates.

JournalNotOpen

Bases: StorageError

A journal was used before it was bound to a participant.

JournalCorrupt

Bases: StorageError

A complete record failed its checksum. This is corruption, not a tail.

exception_for

exception_for(status: int, **context: Any) -> PaxodinError

Build the exception that matches a status code.

Parameters:

Name	Type	Description	Default
status	int	A bridge or protocol status code.	required
**context	Any	Structured detail to attach.	{}

Returns:

Type	Description
PaxodinError	The most specific exception class for the code, or a generic
PaxodinError	ProtocolError / NativeError when none is registered.

raise_for

raise_for(status: int, **context: Any) -> None

Raise if a native call reported failure.

Parameters:

Name	Type	Description	Default
status	int	The status a native call returned.	required
**context	Any	Structured detail to attach.	{}

Raises:

Type	Description
PaxodinError	When status is not success.