Cause

Records the full reason an Effect failed.

A Cause<E> can contain typed failures, unexpected defects, interruptions, and annotations. Keeping those details together lets code inspect or format failures without first collapsing them to a single error value. This module includes the Cause and Reason data types, helpers for building and checking causes, and small error types used by several Effect APIs.

75 exports Added in v2.0.0 Source

Annotations

annotate

Added in v4.0.0 Source

Attaches metadata to every reason in a Cause.

When to use

Use to attach diagnostic metadata to every reason in a cause.

Details

Annotations are stored as a Context on each reason and can be retrieved later via reasonAnnotations or annotations. The runtime uses this to attach stack traces and spans.

- Returns a new Cause. - By default, existing keys are preserved. Pass { overwrite: true } to replace them.

See

annotations for reading merged annotations from a cause
reasonAnnotations for reading annotations from a single reason

Signature

declare const annotate: {
  (
    annotations: Context<never>,
    options?: {
      readonly overwrite?: boolean;
    },
  ): <E>(self: Cause<E>) => Cause<E>;
  <E>(
    self: Cause<E>,
    annotations: Context<never>,
    options?: {
      readonly overwrite?: boolean;
    },
  ): Cause<E>;
};

annotations

Added in v4.0.0 Source

Reads the merged annotations from all reasons in a Cause.

When to use

Use to read diagnostic metadata merged from the whole cause.

Gotchas

When multiple reasons contain the same annotation key, the value from the later reason wins.

See

reasonAnnotations — annotations from a single reason

Signature

declare const annotations: <E>(self: Cause<E>) => Context.Context<never>;

reasonAnnotations

Added in v4.0.0 Source

Reads the annotations from a single Reason as a Context.

When to use

Use when you need tracing metadata (e.g. StackTrace) from a specific reason rather than the whole cause.

See

annotations — merged annotations from all reasons in a cause

Signature

declare const reasonAnnotations: <E>(self: Reason<E>) => Context.Context<never>;

Combining

combine

Added in v4.0.0 Source

Merges two causes into a single cause whose reasons array is the union of both inputs (de-duplicated by value equality).

When to use

Use to merge independent causes into one structured failure value.

Details

- Combining with empty returns the other cause unchanged. - If the result is structurally equal to self, self is returned (referential shortcut).

See

fromReasons — build a cause from an array of reasons
empty for the identity cause used when combining

Signature

declare const combine: {
  <E2>(that: Cause<E2>): <E>(self: Cause<E>) => Cause<E2 | E>;
  <E, E2>(self: Cause<E>, that: Cause<E2>): Cause<E | E2>;
};

Constructors

AsyncFiberError

Added in v4.0.0 Source

Constructs an AsyncFiberError for a fiber that could not be resolved synchronously.

When to use

Use to create the error value for a fiber that could not be completed by a synchronous runner.

See

isAsyncFiberError for checking unknown values

Signature

declare const AsyncFiberError: (fiber: Fiber<unknown, unknown>) => AsyncFiberError;

die

Added in v2.0.0 Source

Creates a Cause containing a single Die reason with the given defect.

When to use

Use to construct a cause from an untyped defect or unexpected thrown value.

See

fail — for typed errors
interrupt — for fiber interruptions

Signature

declare const die: (defect: unknown) => Cause<never>;

done

Added in v4.0.0 Source

Creates an Effect that fails with a Done error. Shorthand for Effect.fail(Cause.Done(value)).

When to use

Use when you model stream or queue completion through the error channel.

See

Done — create the signal value without an Effect

Signature

declare const done: <A = void>(value?: A) => Effect.Effect<never, Done<A>>;

Done

Added in v4.0.0 Source

Creates a Done signal with an optional value.

When to use

Use when you need to construct a low-level pull completion signal directly.

See

done — create a failing Effect with Done

Signature

declare const Done: <A = void>(value?: A) => Done<A>;

empty

Added in v2.0.0 Source

Represents a Cause with an empty reasons array.

When to use

Use to represent the absence of failure when constructing or combining causes.

Details

Represents the absence of failure. Combining any cause with empty via combine returns the original cause unchanged.

See

combine for merging causes where empty acts as the identity

Signature

declare const empty: Cause<never>;

ExceededCapacityError

Added in v4.0.0 Source

Constructs an ExceededCapacityError with an optional message.

When to use

Use to create the error value for bounded-resource capacity failures.

See

isExceededCapacityError for checking unknown values

Signature

declare const ExceededCapacityError: (message?: string) => ExceededCapacityError;

fail

Added in v2.0.0 Source

Creates a Cause containing a single Fail reason with the given typed error.

When to use

Use to construct a cause from an expected typed error.

See

die — for untyped defects
interrupt — for fiber interruptions

Signature

declare const fail: <E>(error: E) => Cause<E>;

fromReasons

Added in v4.0.0 Source

Creates a Cause from an array of Reason values.

When to use

Use when you already have individual reasons (e.g. from filtering or transforming another cause's reasons array) and need to wrap them back into a Cause.

Details

- Returns a new Cause. - An empty array produces a cause equivalent to empty.

Gotchas

The reasons array is stored as provided. Treat the array as immutable after passing it to this function.

See

combine — merge two existing causes

Signature

declare const fromReasons: <E>(reasons: ReadonlyArray<Reason<E>>) => Cause<E>;

IllegalArgumentError

Added in v4.0.0 Source

Constructs an IllegalArgumentError with an optional message.

Signature

declare const IllegalArgumentError: (message?: string) => IllegalArgumentError;

interrupt

Added in v2.0.0 Source

Creates a Cause containing a single Interrupt reason, optionally carrying the interrupting fiber's ID.

See

fail — for typed errors
die — for untyped defects

Signature

declare const interrupt: (fiberId?: number) => Cause<never>;

makeDieReason

Added in v4.0.0 Source

Creates a standalone Die reason (not wrapped in a Cause).

When to use

Use when constructing a standalone defect reason for fromReasons or direct comparison.

See

makeFailReason — create a Fail reason
makeInterruptReason — create an Interrupt reason

Signature

declare function makeDieReason(defect: unknown): Die;

makeFailReason

Added in v4.0.0 Source

Creates a standalone Fail reason (not wrapped in a Cause).

When to use

Use when constructing a standalone typed failure reason for fromReasons or direct comparison.

See

makeDieReason — create a Die reason
makeInterruptReason — create an Interrupt reason

Signature

declare function makeFailReason<E>(error: E): Fail<E>;

makeInterruptReason

Added in v4.0.0 Source

Creates a standalone Interrupt reason (not wrapped in a Cause), optionally carrying the interrupting fiber's ID.

When to use

Use when constructing a standalone interrupt reason for fromReasons or direct comparison.

See

makeFailReason — create a Fail reason
makeDieReason — create a Die reason

Signature

declare const makeInterruptReason: (fiberId?: number) => Interrupt;

NoSuchElementError

Added in v4.0.0 Source

Constructs a NoSuchElementError with an optional message.

When to use

Use to create the error value for APIs that intentionally fail when an expected element is absent.

See

isNoSuchElementError for checking unknown values

Signature

declare const NoSuchElementError: (message?: string) => NoSuchElementError;

TimeoutError

Added in v4.0.0 Source

Constructs a TimeoutError with an optional message.

Signature

declare const TimeoutError: (message?: string) => TimeoutError;

UnknownError

Added in v4.0.0 Source

Constructs an UnknownError. The first argument is the original cause (stored in Error.cause); the second is an optional human-readable message.

Signature

declare const UnknownError: (cause: unknown, message?: string) => UnknownError;

Destructors

squash

Added in v2.0.0 Source

Collapses a Cause into a single unknown value, picking the "most important" failure in this order:

When to use

Use to collapse a structured cause to the single value that synchronous and promise runners would throw.

Details

1. First Fail error (the E value) 2. First Die defect 3. A generic Error("All fibers interrupted without error") for interrupt-only causes 4. A generic Error("Empty cause") for empty

This is the function used by Effect.runPromise and Effect.runSync to decide what to throw.

Gotchas

This function is lossy. Use prettyErrors or iterate cause.reasons when you need all failures.

See

prettyErrors — non-lossy conversion to Array<Error>
pretty — human-readable string rendering

Signature

declare const squash: <E>(self: Cause<E>) => unknown;

interface ExceededCapacityError extends YieldableError {
  readonly _tag: "ExceededCapacityError";
  readonly "~effect/Cause/ExceededCapacityError": "~effect/Cause/ExceededCapacityError";
}

IllegalArgumentError interface

Added in v4.0.0 Source

An error indicating that a function received an argument that violates its contract (e.g. negative where positive was expected).

Details

Implements YieldableError.

Signature

interface IllegalArgumentError extends YieldableError {
  readonly _tag: "IllegalArgumentError";
  readonly "~effect/Cause/IllegalArgumentError": "~effect/Cause/IllegalArgumentError";
}

NoSuchElementError interface

Added in v4.0.0 Source

An error indicating that an expected value was absent.

When to use

Use to model APIs that intentionally turn absence into an error.

Details

Used by APIs that convert absence into an exception or effect failure, such as Option.getOrThrow. Implements YieldableError so it can be yielded directly in Effect.gen.

Gotchas

Prefer APIs that return Option or a typed failure when absence is an expected case. This error is mainly for APIs that intentionally turn absence into a thrown value or failed effect.

Signature

interface NoSuchElementError extends YieldableError {
  readonly _tag: "NoSuchElementError";
  readonly "~effect/Cause/NoSuchElementError": "~effect/Cause/NoSuchElementError";
}

TimeoutError interface

Added in v4.0.0 Source

An error indicating that an operation exceeded its time limit.

Details

Produced by Effect.timeout and related APIs. Implements YieldableError.

Signature

interface TimeoutError extends YieldableError {
  readonly _tag: "TimeoutError";
  readonly "~effect/Cause/TimeoutError": "~effect/Cause/TimeoutError";
}

UnknownError interface

Added in v4.0.0 Source

A wrapper for errors whose type is not statically known.

Details

Used when a thrown or rejected value is not represented by a more specific typed error. The original value is stored in the cause property inherited from Error. Implements YieldableError.

Signature

interface UnknownError extends YieldableError {
  readonly _tag: "UnknownError";
  readonly "~effect/Cause/UnknownError": "~effect/Cause/UnknownError";
}

YieldableError interface

Added in v2.0.0 Source

Base interface for error classes that can be yielded directly inside Effect.gen. Yielding one of these errors fails the generator with that error as the typed failure value.

Details

All built-in error classes in this module (NoSuchElementError, TimeoutError, IllegalArgumentError, ExceededCapacityError, AsyncFiberError, and UnknownError) implement this interface.

Signature

interface YieldableError extends Error, Pipeable, Inspectable {
  readonly "~effect/Effect": Variance<never, YieldableError, never>;
  [iterator](): EffectIterator<Effect<never, YieldableError, never>>;
}

Filtering

filterInterruptors

Added in v4.0.0 Source

Returns a Result whose success value is the set of defined fiber IDs from the cause's Interrupt reasons. If the cause has no Interrupt reason, the failure value is the original cause.

When to use

Use when you need absence of interrupt reasons to fail with the original cause.

Gotchas

Interrupt reasons without a fiberId still count as interrupts, so the function succeeds with an empty Set when every interrupt reason has an undefined fiber ID.

See

interruptors — always-succeeding variant

Signature

declare const filterInterruptors: <E>(self: Cause<E>) => Result.Result<Set<number>, Cause<E>>;

findDefect

Added in v4.0.0 Source

Returns a Result whose success value is the first defect value from a Die reason in the cause. If the cause has no Die reason, the failure value is the original cause.

When to use

Use when you need the first defect value from a Cause as a Result, without the full Die reason.

See

findDie — extract the full Die reason
findError — extract the first typed error

Signature

declare const findDefect: <E>(self: Cause<E>) => Result.Result<unknown, Cause<E>>;

findDie

Added in v4.0.0 Source

Returns a Result whose success value is the first Die reason in the cause, including its annotations. If the cause has no Die reason, the failure value is the original cause.

When to use

Use when you need the full Die reason from a Cause, including annotations.

See

findDefect — extract the unwrapped defect value
findFail — extract the first Fail reason

Signature

declare const findDie: <E>(self: Cause<E>) => Result.Result<Die, Cause<E>>;

findError

Added in v4.0.0 Source

Returns a Result whose success value is the first typed error value E from a Fail reason in the cause. If the cause has no Fail reason, the failure value is the original cause narrowed to Cause<never>, because it contains no typed error reasons.

When to use

Use when you need the first typed error value from a Cause as a Result that preserves the original cause when no match is found.

See

findFail — extract the full Fail reason
findErrorOption — Option-based variant

Signature

declare const findError: <E>(self: Cause<E>) => Result.Result<E, Cause<never>>;

findErrorOption

Added in v4.0.0 Source

Returns the first typed error value E from a cause wrapped in Option.some, or Option.none if no Fail reason exists.

When to use

Use when you need the first typed error value from a Cause as an Option, discarding the original cause.

See

findError — Result-based variant

Signature

declare const findErrorOption: <E>(input: Cause<E>) => Option<E>;

findFail

Added in v4.0.0 Source

Returns a Result whose success value is the first Fail reason in the cause, including its annotations. If the cause has no Fail reason, the failure value is the original cause narrowed to Cause<never>, because it contains no typed error reasons.

When to use

Use when you need the full Fail reason from a Cause, including annotations.

See

findError — extract the unwrapped E value
findDie — extract the first Die reason

Signature

declare const findFail: <E>(self: Cause<E>) => Result.Result<Fail<E>, Cause<never>>;

findInterrupt

Added in v4.0.0 Source

Returns a Result whose success value is the first Interrupt reason in the cause, including its annotations. If the cause has no Interrupt reason, the failure value is the original cause.

When to use

Use when you need the first Interrupt reason from a Cause, including the fiber ID and annotations.

See

interruptors — collect all interrupting fiber IDs as a Set

Signature

declare const findInterrupt: <E>(self: Cause<E>) => Result.Result<Interrupt, Cause<E>>;

Formatting

pretty

Added in v2.0.0 Source

Formats a Cause as a human-readable string for logging or debugging.

When to use

Use to render a whole cause as one human-readable string for logs or diagnostics.

Details

Delegates to prettyErrors to convert each reason to an Error, then joins their stack traces with newlines. Nested Error.cause chains are rendered inline with indentation:

``text ErrorName: message at ... at ... { [cause]: NestedError: message at ... } ``

Span annotations are appended to the relevant stack frames when available.

Gotchas

Rendering an empty cause produces an empty string because there are no errors to render.

See

prettyErrors — get the individual Error instances

Signature

declare const pretty: <E>(cause: Cause<E>) => string;

prettyErrors

Added in v3.2.0 Source

Converts a Cause into an Array<Error> suitable for logging or rethrowing.

When to use

Use to convert every renderable failure in a cause into individual Error values before logging or rethrowing.

Details

Each Fail and Die reason is converted into a standard Error:

- Objects / Error instances — message, name, stack, and cause are preserved. Extra enumerable properties are copied. Stack traces are cleaned up and enriched with span annotations when available. - Strings — used directly as the Error message. - Other primitives (null, undefined, numbers, …) — wrapped in an Error with message "Unknown error: <value>".

Interrupt reasons are collected separately. If the cause contains only interrupts (no Fail or Die), a single InterruptError is returned whose cause lists the interrupting fiber IDs.

An empty cause returns an empty array.

See

pretty — renders the cause as a single string
squash — lossy collapse to a single thrown value

Signature

declare const prettyErrors: <E>(
  self: Cause<E>,
  options?: {
    readonly includeCauseInStack?: boolean;
  },
) => Array<Error>;

Getters

interruptors

Added in v2.0.0 Source

Collects the defined fiber IDs from all Interrupt reasons in the cause into a ReadonlySet. Interrupt reasons without a fiberId are ignored. Returns an empty set when the cause has no interrupting fiber IDs.

When to use

Use when you need interrupting fiber IDs as a set, with absence represented as an empty set.

See

filterInterruptors — Result-based variant

Signature

declare const interruptors: <E>(self: Cause<E>) => ReadonlySet<number>;

Guards

isAsyncFiberError

Added in v4.0.0 Source

Checks whether an arbitrary value is an AsyncFiberError.

Signature

declare const isAsyncFiberError: (u: unknown) => u is AsyncFiberError;

isCause

Added in v2.0.0 Source

Checks whether an arbitrary value is a Cause.

Signature

declare const isCause: (self: unknown) => self is Cause<unknown>;

isDieReason

Added in v4.0.0 Source

Narrows a Reason to Die.

When to use

Use as a predicate for Array.filter to pick out Die (defect) reasons when iterating over cause.reasons.

See

isFailReason — narrow to Fail
isInterruptReason — narrow to Interrupt

Signature

declare const isDieReason: <E>(self: Reason<E>) => self is Die;

isDone

Added in v4.0.0 Source

Checks whether an arbitrary value is a Done signal.

Signature

declare const isDone: (u: unknown) => u is Done<any>;

isExceededCapacityError

Added in v4.0.0 Source

Checks whether an arbitrary value is an ExceededCapacityError.

Signature

declare const isExceededCapacityError: (u: unknown) => u is ExceededCapacityError;

isFailReason

Added in v4.0.0 Source

Narrows a Reason to Fail.

When to use

Use as a predicate for Array.filter to pick out typed Fail reasons when iterating over cause.reasons.

See

isDieReason — narrow to Die
isInterruptReason — narrow to Interrupt

Signature

declare const isFailReason: <E>(self: Reason<E>) => self is Fail<E>;

isIllegalArgumentError

Added in v4.0.0 Source

Checks whether an arbitrary value is an IllegalArgumentError.

Signature

declare const isIllegalArgumentError: (u: unknown) => u is IllegalArgumentError;

isInterruptReason

Added in v4.0.0 Source

Narrows a Reason to Interrupt.

When to use

Use as a predicate for Array.filter to pick out Interrupt reasons when iterating over cause.reasons.

See

isFailReason — narrow to Fail
isDieReason — narrow to Die

Signature

declare const isInterruptReason: <E>(self: Reason<E>) => self is Interrupt;

isNoSuchElementError

Added in v4.0.0 Source

Checks whether an arbitrary value is a NoSuchElementError.

Signature

declare const isNoSuchElementError: (u: unknown) => u is NoSuchElementError;

isReason

Added in v4.0.0 Source

Checks whether an arbitrary value is a Reason (Fail, Die, or Interrupt).

Signature

declare const isReason: (self: unknown) => self is Reason<unknown>;

isTimeoutError

Added in v4.0.0 Source

Checks whether an arbitrary value is a TimeoutError.

Signature

declare const isTimeoutError: (u: unknown) => u is TimeoutError;

isUnknownError

Added in v4.0.0 Source

Checks whether an arbitrary value is an UnknownError.

Signature

declare const isUnknownError: (u: unknown) => u is UnknownError;

Mapping

map

Added in v2.0.0 Source

Transforms the typed error values inside a Cause using the provided function. Only Fail reasons are affected; Die and Interrupt reasons pass through unchanged.

When to use

Use to transform expected typed failures while preserving defects and interruptions unchanged.

Details

If at least one Fail reason exists, this returns a new Cause containing the mapped failures. If the cause has no Fail reasons, the original cause is returned unchanged.

Signature

declare const map: {
  <E, E2>(f: (error: NoInfer<E>) => E2): (self: Cause<E>) => Cause<E2>;
  <E, E2>(self: Cause<E>, f: (error: NoInfer<E>) => E2): Cause<E2>;
};

Models

Cause interface

Added in v2.0.0 Source

A structured representation of how an Effect failed.

When to use

Use to preserve the full structured failure information for an effect instead of collapsing it to a single error value.

Details

Access the individual failure entries through the reasons array, then narrow each entry with isFailReason, isDieReason, or isInterruptReason.

- Use hasFails / hasDies / hasInterrupts to test for the presence of specific reason kinds without iterating. - Use findError / findDefect to extract the first value of a given kind. - Use combine to merge two causes.

Cause implements Equal — two causes with the same reasons (by value) compare as equal.

Signature

interface Cause<out E> extends Pipeable, Inspectable, Equal {
  readonly "~effect/Cause": "~effect/Cause";
  readonly reasons: readonly Array<Reason<E>>;
}

Die interface

Added in v2.0.0 Source

An untyped defect — typically a programming error or an uncaught exception.

When to use

Use when inspecting Cause reasons that represent defects instead of typed failures or interruptions.

Details

The defect property is unknown because defects are not part of the typed error channel. Use isDieReason to narrow a Reason to this type.

See

die for constructing a cause with a single Die reason
isDieReason for narrowing a Reason to Die

Signature

interface Die extends ReasonProto<"Die"> {
  readonly defect: unknown;
}

Fail interface

Added in v2.0.0 Source

A typed, expected error produced by Effect.fail.

When to use

Use when inspecting Cause reasons that represent expected failures from the typed error channel.

Details

The error property carries the typed value E. Use isFailReason to narrow a Reason to this type.

See

fail for constructing a cause with a single Fail reason
isFailReason for narrowing a Reason to Fail

Signature

interface Fail<out E> extends ReasonProto<"Fail"> {
  readonly error: E;
}

Interrupt interface

Added in v2.0.0 Source

A fiber interruption signal, optionally carrying the ID of the fiber that initiated the interruption.

Details

Use isInterruptReason to narrow a Reason to this type.

Signature

interface Interrupt extends ReasonProto<"Interrupt"> {
  readonly fiberId: number | undefined;
}

Reason type

Added in v4.0.0 Source

A single entry inside a Cause's reasons array.

Details

Narrow to a concrete type with isFailReason, isDieReason, or isInterruptReason.

- Fail<E> — typed error, access via .error - Die — untyped defect, access via .defect - Interrupt — fiber interruption, access via .fiberId

Every reason carries an annotations map and an annotate method for attaching tracing metadata.

Signature

type Reason<E> = Fail<E> | Die | Interrupt;

Other

Cause

Added in v2.0.0 Source

Companion namespace for the Cause interface.

Done

Added in v4.0.0 Source

Companion namespace for the Done interface.

Reason

Added in v4.0.0 Source

Companion namespace for the Reason type.

Predicates

hasDies

Added in v4.0.0 Source

Returns true if the cause contains at least one Die reason.

When to use

Use to check whether a cause includes defects before extracting or rendering them.

See

hasFails — check for typed errors
hasInterrupts — check for interruptions

Signature

declare const hasDies: <E>(self: Cause<E>) => boolean;

hasFails

Added in v4.0.0 Source

Returns true if the cause contains at least one Fail reason.

When to use

Use to check whether a cause includes typed failures before extracting, mapping, or rendering them.

See

hasDies — check for defects
hasInterrupts — check for interruptions

Signature

declare const hasFails: <E>(self: Cause<E>) => boolean;

hasInterrupts

Added in v4.0.0 Source

Returns true if the cause contains at least one Interrupt reason.

See

hasInterruptsOnly — true only when *all* reasons are interrupts
hasFails — check for typed errors
hasDies — check for defects

Signature

declare const hasInterrupts: <E>(self: Cause<E>) => boolean;

hasInterruptsOnly

Added in v4.0.0 Source

Returns true if every reason in the cause is an Interrupt (and there is at least one reason).

When to use

Use when you need to detect failures caused only by interruption.

See

hasInterrupts — true if the cause contains *any* interrupts

Signature

declare const hasInterruptsOnly: <E>(self: Cause<E>) => boolean;

Services

InterruptorStackTrace

Added in v4.0.0 Source

Context annotation used to store the stack frame captured at the point of interruption.

When to use

Use when you need the stack-frame annotation used by interrupt-only cause rendering.

Details

Similar to StackTrace but specific to Interrupt reasons.

See

StackTrace for stack frames attached to failures
reasonAnnotations for reading annotations from a single reason
annotate for attaching annotations to a cause

Signature

declare class InterruptorStackTrace extends Shape<
  "effect/Cause/InterruptorStackTrace",
  StackFrame,
  this
> {
  constructor(_: never);
}

StackTrace

Added in v4.0.0 Source

Context annotation used to store the stack frame captured at the point of failure.

When to use

Use to read the failure stack-frame annotation from a Reason when building diagnostics, logging, or custom cause renderers.

Details

The runtime annotates every reason with this when a stack frame is available. Retrieve it via Context.get(Cause.reasonAnnotations(reason), Cause.StackTrace).

See

reasonAnnotations for reading annotations from a single reason
annotations for reading merged annotations from a cause
InterruptorStackTrace for the interrupt-specific stack-frame annotation

Signature

declare class StackTrace extends Shape<"effect/Cause/StackTrace", StackFrame, this> {
  constructor(_: never);
}

declare const UnknownErrorTypeId: "~effect/Cause/UnknownError";