Skip to content

ClusterError

Defines the structured errors used by the unstable cluster runtime.

These tagged, schema-backed errors describe failures at routing, runner membership, serialization, persistence, mailbox capacity, and duplicate envelope boundaries. Cluster clients, runners, and storage adapters use these shared error values to report failures through typed Effect errors.

7 exports Added in v4.0.0 Source

Errors

AlreadyProcessingMessage

Added in v4.0.0 Source

Represents an error that occurs when the same request envelope is already being processed.

Details

Carries the address and envelopeId for the affected request envelope.

Signature

declare class AlreadyProcessingMessage extends {
  readonly _tag: "AlreadyProcessingMessage";
  readonly address: EntityAddress;
  readonly envelopeId: bigint & Brand<"~effect/cluster/Snowflake">;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "AlreadyProcessingMessage";
    readonly address: EntityAddress;
    readonly envelopeId: bigint & Brand<"~effect/cluster/Snowflake">;
  }, options?: MakeOptions]);
  readonly "~effect/cluster/ClusterError": "~effect/cluster/ClusterError";
  static is(u: unknown): u is AlreadyProcessingMessage;
}

EntityNotAssignedToRunner

Added in v4.0.0 Source

Represents an error that occurs when a Runner receives a message for an entity that is not assigned to the receiving runner.

Signature

declare class EntityNotAssignedToRunner extends {
  readonly _tag: "EntityNotAssignedToRunner";
  readonly address: EntityAddress;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "EntityNotAssignedToRunner";
    readonly address: EntityAddress;
  }, options?: MakeOptions]);
  readonly "~effect/cluster/ClusterError": "~effect/cluster/ClusterError";
  static is(u: unknown): u is EntityNotAssignedToRunner;
}

MailboxFull

Added in v4.0.0 Source

Represents an error that occurs when the entity mailbox is full.

Details

Carries the address whose bounded mailbox is at capacity.

Gotchas

Volatile requests fail immediately. Persisted or durable messages are retried or resumed from storage when the mailbox is full.

Signature

declare class MailboxFull extends {
  readonly _tag: "MailboxFull";
  readonly address: EntityAddress;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "MailboxFull";
    readonly address: EntityAddress;
  }, options?: MakeOptions]);
  readonly "~effect/cluster/ClusterError": "~effect/cluster/ClusterError";
  static is(u: unknown): u is MailboxFull;
}

MalformedMessage

Added in v4.0.0 Source

Represents an error that occurs when a message fails at a schema serialization or deserialization boundary.

Details

cause carries the underlying failure. refail maps encode and decode failures into MalformedMessage values.

Signature

declare class MalformedMessage extends {
  readonly _tag: "MalformedMessage";
  readonly cause: unknown;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "MalformedMessage";
    readonly cause: unknown;
  }, options?: MakeOptions]);
  readonly "~effect/cluster/ClusterError": "~effect/cluster/ClusterError";
  static refail: <A, E, R>(effect: Effect<A, E, R>) => Effect<A, MalformedMessage, R>;
  static is(u: unknown): u is MalformedMessage;
}

PersistenceError

Added in v4.0.0 Source

Represents an error that occurs when a message fails to be persisted into cluster's mailbox storage.

Signature

declare class PersistenceError extends {
  readonly _tag: "PersistenceError";
  readonly cause: unknown;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "PersistenceError";
    readonly cause: unknown;
  }, options?: MakeOptions]);
  readonly "~effect/cluster/ClusterError": "~effect/cluster/ClusterError";
  static refail<A, E, R>(effect: Effect<A, E, R>): Effect<A, PersistenceError, R>;
}

RunnerNotRegistered

Added in v4.0.0 Source

Represents an error that occurs when a Runner is not registered with the shard manager.

Signature

declare class RunnerNotRegistered extends {
  readonly _tag: "RunnerNotRegistered";
  readonly address: RunnerAddress;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "RunnerNotRegistered";
    readonly address: RunnerAddress;
  }, options?: MakeOptions]);
  readonly "~effect/cluster/ClusterError": "~effect/cluster/ClusterError";
}

RunnerUnavailable

Added in v4.0.0 Source

Represents an error that occurs when a Runner is unresponsive.

Signature

declare class RunnerUnavailable extends {
  readonly _tag: "RunnerUnavailable";
  readonly address: RunnerAddress;
} & YieldableError<this> {
  constructor(...args: [props: {
    readonly _tag?: "RunnerUnavailable";
    readonly address: RunnerAddress;
  }, options?: MakeOptions]);
  readonly "~effect/cluster/ClusterError": "~effect/cluster/ClusterError";
  static is(u: unknown): u is RunnerUnavailable;
}