tractor/docs/api/errors.rst

Errors and cancellation types

tractor extends trio's "exceptions always propagate" rule across the process boundary: a crash in any actor is serialized as an Error msg, shuttled over IPC, and re-raised in the linked parent scope as a boxed RemoteActorError — preserving the original type, traceback text and source-actor identity, even across multi-hop relays (a.k.a. "inceptions").

The most-used types below are importable from tractor directly; the remainder live in tractor._exceptions (not yet re-exported at top level).

tractor

Boxed remote errors

RemoteActorError

try:
    async with portal.open_context(ep_fn) as (ctx, first):
        ...
except tractor.RemoteActorError as rae:
    if rae.boxed_type is ValueError:
        ...  # remote task raised a `ValueError`

ContextCancelled

Note

Inspect ContextCancelled.canceller (the requesting actor's uid) to distinguish a self-requested cancel (absorbed at open_context() exit) from a cross-actor cancel (raised locally) — the full rules live in /api/context.

Typed-messaging errors

MsgTypeError

An "IPC TypeError": a message failed validation against the active msg-spec / pld_spec (see /api/msg). Raised sender-side for control msgs (Started/Return) and receiver-side for stream Yield payloads.

tractor._exceptions.StreamOverrun

The sender out-paced the receiver's buffer on a ~tractor.MsgStream opened without allow_overruns=True; subtypes trio.TooSlowError.

Transport and runtime errors

TransportClosed

ModuleNotExposed

Raised when an RPC requests a function from a module not listed in the target actor's enable_modules allowlist — capability-style access control, not an import bug on your end ;)

tractor._exceptions.NoRuntime

Raised by tractor.current_actor (and friends) when no actor runtime is up in the current process.

tractor._exceptions.ActorTooSlowError

A peer actor failed to ack a cancel request within the bounded wait — the SC-sanctioned escalation signal from APIs like Portal.cancel_actor(raise_on_timeout=True). Catch it to escalate (e.g. hard-kill via the supervising ~tractor.ActorNursery); never just ignore it, that's how zombies happen.

/api/context for how cancellation and errors flow through a ~tractor.Context, /api/devx for crash-handling REPL tooling (debug_mode, post-mortems), and /guide/cancellation for the full SC-cancellation story.