Errors

The public API fails in two shapes: sentinel errors and class errors. Whether a failure is returned, thrown, or rejected depends on the call site: PID.tell returns the error, ctx.tell throws it, and async methods reject with it. Each reference page documents the form at the point of use; this page is the index.

Sentinels

Sentinel errors are singleton Error values. The same object represents that failure everywhere. Compare them by identity:

import { ErrDead, ErrMailboxFull } from "@tochemey/nodeakt";

const err = outside.tell(target, message);
if (err === ErrDead || err === ErrMailboxFull) {
  // ...
}

Sentinel	Arises when
ErrActorAlreadyExists	system.spawn with a top-level name that is still held, including by a suspended or currently stopping actor.
ErrActorSystemNotStarted	spawn, noSender, subscribe, unsubscribe, or any scheduling call on a system that is not running.
ErrDead	The actor is not running: tell / ask to a stopped target, registering a schedule whose target has stopped, or spawnChild, ctx.child, ctx.stop, restart through a stopped actor. Also the dead-letter reason for a send through a router with no live routee.
ErrFanOutAsk	An ask or request through a fan-out router; a broadcast has no single answer.
ErrInvalidActorName	An actor name is empty, longer than 255 characters, or syntactically invalid.
ErrInvalidActorSystemName	A system name violates the system-name syntax (stricter than actor names).
ErrInvalidInterval	schedule / scheduleOnce with a delay or interval that is not a positive number.
ErrInvalidPoolSize	spawnRouter with a pool size that is not a positive integer, or an AdjustRouterPoolSize whose size is not a non-negative integer.
ErrInvalidReentrancyMode	An unknown reentrancy mode at spawn or on request options.
ErrInvalidRouteeDirective	spawnRouter with an unknown routee directive.
ErrInvalidRoutingStrategy	spawnRouter with an unknown routing strategy.
ErrInvalidTimeout	Reserved. ask and request now fall back to the system askTimeout for a non-positive timeout instead of raising this.
ErrMailboxDisposed	Enqueue on a mailbox after the actor stopped, or ctx.stash while the actor is stopping.
ErrMailboxFull	A bounded mailbox is at capacity.
ErrNameRequired	The system name is empty.
ErrPipeTimeout	A pipe's timeout expired before its task settled. The reason on the resulting dead letter; nothing is delivered.
ErrReentrancyDisabled	ctx.request without a reentrancy config, or with mode off.
ErrReentrancyInFlightLimit	A request past the actor's maxInFlight cap.
ErrRemotingDisabled	A remote operation such as remoteLookup on a system created without a remote configuration. See Remoting.
ErrRequestCanceled	A request completed by cancel().
ErrRequestTimeout	An ask or request unanswered within one to two timeout periods.
ErrReservedName	A name starting with the reserved prefix NodeAkt.
ErrRoutingKeyRequired	spawnRouter with the consistent-hash strategy and no routing key extractor.
ErrScheduleAlreadyExists	Registering a schedule under a reference that is already held.
ErrScheduleNotFound	cancelSchedule, pauseSchedule, or resumeSchedule with a reference no schedule holds.
ErrStashBufferEmpty	ctx.unstash with nothing stashed.
ErrUndefinedActor	ctx.stop on the PID that represents an absent sender.
ErrUndefinedTask	pipeTo or pipeToName given a null or undefined task. The reason on the resulting dead letter; nothing is delivered.
ErrUnhandled	The Deadletter reason after ctx.unhandled.

Classes

Class errors are constructed per failure and carry context. Inspect them with instanceof. Their name field matches the class name.

Class	Arises when
ActorInitializationError	preStart failed during spawn or system start. The underlying failure is on error.cause; the actor is not registered.
ActorNotFoundError	ctx.child with no running child of that name, ctx.stop on a PID that is not a live child of this actor, or a pipeToName settling when no running top-level actor holds the name.
ActorNotRegisteredError	A Props spawn whose class was never registerActor'd.

Standard errors

The runtime also uses built-ins where the mistake is in the calling code:

• TypeError: registerActor / registerMessage misuse, a Props spawn with live options or non-cloneable constructor arguments, and shutdown() on a handle whose actor is owned by another isolate.
• RangeError: a mailbox or passivation constructor given a capacity, timeout, or count that is not a positive number.