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>;
}

Example

(Annotating a cause)

import { Cause, Context } from "effect"

class RequestId extends Context.Service<RequestId, string>()("RequestId") {}

const annotated = Cause.annotate(Cause.fail("error"), Context.make(RequestId, "req-1"))
Context.getOrUndefined(Cause.annotations(annotated), RequestId) // => "req-1"

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>

Example

(Reading merged annotations)

import { Cause, Context } from "effect"

class RequestId extends Context.Service<RequestId, string>()("RequestId") {}

const cause = Cause.annotate(
  Cause.fail("error"),
  Context.make(RequestId, "req-1")
)

Context.getOrUndefined(Cause.annotations(cause), RequestId) // => "req-1"

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>

Example

(Reading reason annotations)

import { Cause, Context } from "effect"

class RequestId extends Context.Service<RequestId, string>()("RequestId") {}

const reason = Cause.makeFailReason("error")
const annotated = reason.annotate(Context.make(RequestId, "req-1"))

Context.getOrUndefined(Cause.reasonAnnotations(annotated), RequestId) // => "req-1"

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>;
}

Example

(Combining two causes)

import { Cause } from "effect"

const combined = Cause.combine(Cause.fail("error1"), Cause.fail("error2"))
combined // => Cause.fromReasons([Cause.makeFailReason("error1"), Cause.makeFailReason("error2")])

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

Example

(Creating an AsyncFiberError)

import { Cause, Effect } from "effect"

const fiber = Effect.runFork(Effect.void)

new Cause.AsyncFiberError(fiber).message // => "An asynchronous Effect was executed with Effect.runSync"

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>

Example

(Creating a die cause)

import { Cause } from "effect"

Cause.die("Unexpected") // => Cause.fromReasons([Cause.makeDieReason("Unexpected")])

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>>

Example

(Failing with Done)

import { Cause, Effect, Exit } from "effect"

const program = Cause.done("finished")

await Effect.runPromiseExit(program) // => Exit.fail(Cause.Done("finished"))

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>

Example

(Combining with the empty cause)

import { Cause } from "effect"

Cause.combine(Cause.empty, Cause.fail("boom")) // => Cause.fail("boom")

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

Example

(Creating an ExceededCapacityError)

import { Cause } from "effect"

new Cause.ExceededCapacityError("Queue full").message // => "Queue full"

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>

Example

(Creating a fail cause)

import { Cause } from "effect"

Cause.fail("Something went wrong") // => Cause.fromReasons([Cause.makeFailReason("Something went wrong")])

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>

Example

(Building a cause from reasons)

import { Cause } from "effect"

const reasons = [
  Cause.makeFailReason("err1"),
  Cause.makeFailReason("err2")
]
Cause.fromReasons(reasons) // => Cause.combine(Cause.fail("err1"), Cause.fail("err2"))

IllegalArgumentError

Added in v4.0.0 Source

Constructs an IllegalArgumentError with an optional message.

Signature

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

Example

(Creating an IllegalArgumentError)

import { Cause } from "effect"

new Cause.IllegalArgumentError("Invalid argument").message // => "Invalid argument"

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>

Example

(Creating an interrupt cause)

import { Cause } from "effect"

Cause.interrupt(123) // => Cause.fromReasons([Cause.makeInterruptReason(123)])

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

Example

(Creating a Die reason)

import { Cause } from "effect"

Cause.makeDieReason("bug") // => Cause.die("bug").reasons[0]

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>

Example

(Creating a Fail reason)

import { Cause } from "effect"

Cause.makeFailReason("error") // => Cause.fail("error").reasons[0]

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

Example

(Creating an Interrupt reason)

import { Cause } from "effect"

Cause.makeInterruptReason(42) // => Cause.interrupt(42).reasons[0]

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

Example

(Creating a NoSuchElementError)

import { Cause } from "effect"

new Cause.NoSuchElementError("Element not found").message // => "Element not found"

TimeoutError

Added in v4.0.0 Source

Constructs a TimeoutError with an optional message.

Signature

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

Example

(Creating a TimeoutError)

import { Cause } from "effect"

new Cause.TimeoutError("Operation timed out").message // => "Operation timed out"

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

Example

(Creating an UnknownError)

import { Cause } from "effect"

new Cause.UnknownError({ raw: true }, "Unexpected value").message // => "Unexpected value"

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

First Fail error (the E value)
First Die defect
A generic Error("All fibers interrupted without error") for interrupt-only causes
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

Example

(Squashing a cause)

import { Cause } from "effect"

Cause.squash(Cause.fail("error")) // => "error"
Cause.squash(Cause.die("defect")) // => "defect"

Errors

AsyncFiberError interface

Added in v4.0.0 Source

An error that occurs when trying to run an async fiber with Effect.runSync.

When to use

Use to inspect failures produced when synchronous runners encounter an effect that cannot complete synchronously.

Details

The fiber property stores the fiber that could not be synchronously resolved. This error implements YieldableError.

Signature

interface AsyncFiberError extends YieldableError {
  readonly _tag: "AsyncFiberError";
  readonly "~effect/Cause/AsyncFiberError": "~effect/Cause/AsyncFiberError";
  readonly fiber: Fiber<unknown, unknown>;
}

Example

(Accessing the fiber)

import { Cause, Effect } from "effect"

const fiber = Effect.runFork(Effect.void)

const value = new Cause.AsyncFiberError(fiber)
const isSameFiber = value.fiber === fiber
isSameFiber // => true

Done interface

Added in v4.0.0 Source

A graceful completion signal for queues and streams.

When to use

Use to model normal producer completion through a stream or queue error channel.

Details

Done indicates that a producer has finished normally — no more elements will arrive. It is distinct from an error or interruption; it represents successful completion. The optional value field can carry a final leftover payload.

Signature

interface Done<A = void> {
  readonly _tag: "Done";
  readonly "~effect/Cause/Done": "~effect/Cause/Done";
  readonly value: A;
}

Example

(Signaling queue completion)

import { Cause, Effect, Queue } from "effect"

const program = Effect.gen(function*() {
  const queue = yield* Queue.bounded<number, Cause.Done>(10)
  yield* Queue.offer(queue, 1)
  yield* Queue.end(queue)

  yield* Queue.take(queue)
  const result = yield* Effect.flip(Queue.take(queue))
  return Cause.isDone(result)
})

await Effect.runPromise(program) // => true

ExceededCapacityError interface

Added in v4.0.0 Source

An error indicating that a bounded resource (queue, pool, semaphore, etc.) has exceeded its capacity.

When to use

Use to model bounded-resource failures where an operation cannot proceed because capacity has been exhausted.

Details

Implements YieldableError.

Signature

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>>;
}

Example

(Yielding an error in Effect.gen)

import { Cause, Effect, Exit } from "effect"

const error = new Cause.NoSuchElementError("not found")

const program = Effect.gen(function*() {
  return yield* error // fails the effect with NoSuchElementError
})

await Effect.runPromiseExit(program) // => Exit.fail(error)

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>>

Example

(Extracting interruptors with Result)

import { Cause, Result } from "effect"

Cause.filterInterruptors(Cause.interrupt(1)) // => Result.succeed(new Set([1]))

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>>

Example

(Extracting the first defect)

import { Cause, Result } from "effect"

Cause.findDefect(Cause.die("defect")) // => Result.succeed("defect")

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>>

Example

(Extracting the first Die reason)

import { Cause, Result } from "effect"

Cause.findDie(Cause.die("defect")) // => Result.succeed(Cause.makeDieReason("defect"))

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>>

Example

(Extracting the first error value)

import { Cause, Result } from "effect"

Cause.findError(Cause.fail("error")) // => Result.succeed("error")

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>

Example

(Extracting an error as Option)

import { Cause, Option } from "effect"

Cause.findErrorOption(Cause.fail("error")) // => Option.some("error")
Cause.findErrorOption(Cause.die("defect")) // => Option.none()

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>>

Example

(Extracting the first Fail reason)

import { Cause, Result } from "effect"

Cause.findFail(Cause.fail("error")) // => Result.succeed(Cause.makeFailReason("error"))

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>>

Example

(Extracting the first interrupt)

import { Cause, Result } from "effect"

Cause.findInterrupt(Cause.interrupt(42)) // => Result.succeed(Cause.makeInterruptReason(42))

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:

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

Example

(Rendering a cause)

import { Cause } from "effect"

Cause.pretty(Cause.fail("something went wrong")).includes("something went wrong") // => true

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>

Example

(Converting a cause to errors)

import { Cause } from "effect"

Cause.prettyErrors(Cause.fail(new Error("boom")))[0].message // => "boom"

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>

Example

(Collecting interruptors)

import { Cause } from "effect"

const cause = Cause.combine(
  Cause.interrupt(1),
  Cause.interrupt(2)
)

Cause.interruptors(cause) // => new Set([1, 2])

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

Example

(Checking the runtime type)

import { Cause, Effect } from "effect"

const fiber = Effect.runFork(Effect.void)

const error = new Cause.AsyncFiberError(fiber)
Cause.isAsyncFiberError(error) // => true
Cause.isAsyncFiberError("nope") // => false

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>

Example

(Checking the runtime type)

import { Cause } from "effect"

Cause.isCause(Cause.fail("error")) // => true
Cause.isCause("not a cause") // => false

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

Example

(Filtering die reasons)

import { Cause } from "effect"

const cause = Cause.die("defect")
const dies = cause.reasons.filter(Cause.isDieReason)
dies[0].defect // => "defect"

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>

Example

(Checking the runtime type)

import { Cause } from "effect"

Cause.isDone(Cause.Done()) // => true
Cause.isDone("not done") // => false

isExceededCapacityError

Added in v4.0.0 Source

Checks whether an arbitrary value is an ExceededCapacityError.

Signature

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

Example

(Checking the runtime type)

import { Cause } from "effect"

Cause.isExceededCapacityError(new Cause.ExceededCapacityError()) // => true
Cause.isExceededCapacityError("nope") // => false

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>

Example

(Filtering fail reasons)

import { Cause } from "effect"

const cause = Cause.fail("error")
const fails = cause.reasons.filter(Cause.isFailReason)
fails[0].error // => "error"

isIllegalArgumentError

Added in v4.0.0 Source

Checks whether an arbitrary value is an IllegalArgumentError.

Signature

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

Example

(Checking the runtime type)

import { Cause } from "effect"

Cause.isIllegalArgumentError(new Cause.IllegalArgumentError()) // => true
Cause.isIllegalArgumentError("nope") // => false

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

Example

(Filtering interrupt reasons)

import { Cause } from "effect"

const cause = Cause.interrupt(123)
const interrupts = cause.reasons.filter(Cause.isInterruptReason)
interrupts[0].fiberId // => 123

isNoSuchElementError

Added in v4.0.0 Source

Checks whether an arbitrary value is a NoSuchElementError.

Signature

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

Example

(Checking the runtime type)

import { Cause } from "effect"

Cause.isNoSuchElementError(new Cause.NoSuchElementError()) // => true
Cause.isNoSuchElementError("nope") // => false

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>

Example

(Checking the runtime type)

import { Cause } from "effect"

const reason = Cause.fail("error").reasons[0]
Cause.isReason(reason) // => true
Cause.isReason("not a reason") // => false

isTimeoutError

Added in v4.0.0 Source

Checks whether an arbitrary value is a TimeoutError.

Signature

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

Example

(Checking the runtime type)

import { Cause } from "effect"

Cause.isTimeoutError(new Cause.TimeoutError()) // => true
Cause.isTimeoutError("nope") // => false

isUnknownError

Added in v4.0.0 Source

Checks whether an arbitrary value is an UnknownError.

Signature

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

Example

(Checking the runtime type)

import { Cause } from "effect"

Cause.isUnknownError(new Cause.UnknownError("x")) // => true
Cause.isUnknownError("nope") // => false

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>;
}

Example

(Mapping errors to uppercase)

import { Cause } from "effect"

const cause = Cause.fail("error")
const mapped = Cause.map(cause, (e) => e.toUpperCase())
const reason = mapped.reasons[0]
if (Cause.isFailReason(reason)) {
  reason.error // => "ERROR"
}

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>>;
}

Example

(Creating and inspecting a cause)

import { Cause } from "effect"

Cause.fail("Something went wrong") // => Cause.fail("Something went wrong")

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;
}

Example

(Accessing the defect)

import { Cause } from "effect"

const cause = Cause.die("Unexpected")
const reason = cause.reasons[0]
if (Cause.isDieReason(reason)) {
  reason.defect // => "Unexpected"
}

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;
}

Example

(Accessing the error)

import { Cause } from "effect"

const cause = Cause.fail("Something went wrong")
const reason = cause.reasons[0]
if (Cause.isFailReason(reason)) {
  reason.error // => "Something went wrong"
}

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;
}

Example

(Accessing the fiber ID)

import { Cause } from "effect"

const cause = Cause.interrupt(123)
const reason = cause.reasons[0]
if (Cause.isInterruptReason(reason)) {
  reason.fiberId // => 123
}

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

Example

(Narrowing a reason)

import { Cause } from "effect"

const reason = Cause.fail("error").reasons[0]
if (Cause.isFailReason(reason)) {
  reason.error // => "error"
}

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

Example

(Checking for defects)

import { Cause } from "effect"

Cause.hasDies(Cause.die("defect")) // => true
Cause.hasDies(Cause.fail("error")) // => false

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

Example

(Checking for typed errors)

import { Cause } from "effect"

Cause.hasFails(Cause.fail("error")) // => true
Cause.hasFails(Cause.die("defect")) // => false

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

Example

(Checking for interruptions)

import { Cause } from "effect"

Cause.hasInterrupts(Cause.interrupt(123)) // => true
Cause.hasInterrupts(Cause.fail("error")) // => false

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

Example

(Checking interrupt-only causes)

import { Cause } from "effect"

Cause.hasInterruptsOnly(Cause.interrupt(123)) // => true
Cause.hasInterruptsOnly(Cause.fail("error")) // => false
Cause.hasInterruptsOnly(Cause.empty) // => false

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"