Cause

The Effect<A, E, R> type is polymorphic in error type E, allowing flexibility in handling any desired error type. However, there is often additional information about failures that the error type E alone does not capture.

To address this, Effect uses the Cause<E> data type to store various details such as:

• Unexpected errors or defects
• Stack and execution traces
• Reasons for fiber interruptions

Effect strictly preserves all failure-related information, storing a full picture of the error context in the Cause type. This comprehensive approach enables precise analysis and handling of failures, ensuring no data is lost.

Though Cause values aren’t typically manipulated directly, they underlie errors within Effect workflows, providing access to both concurrent and sequential error details. This allows for thorough error analysis when needed.

Creating Causes

You can intentionally create an effect with a specific cause using Effect.failCause.

Example (Defining Effects with Different Causes)

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

3
// Define an effect that dies with an unexpected error
4
//
5
//      ┌─── Effect<never, never, never>
6
//      ▼
7
const die = Effect.failCause(Cause.die("Boom!"))
8

9
// Define an effect that fails with an expected error
10
//
11
//      ┌─── Effect<never, string, never>
12
//      ▼
13
const fail = Effect.failCause(Cause.fail("Oh no!"))
14

15
Effect.runSyncExit(fail) // => Exit.fail("Oh no!")

Some causes do not influence the error type of the effect, leading to never in the error channel:

                ┌─── no error information
                ▼
Effect<never, never, never>

For instance, Cause.die does not specify an error type for the effect, while Cause.fail does, setting the error channel type accordingly.

Cause Variations

There are several causes for various errors, in this section, we will describe each of these causes.

Empty

The Empty cause signifies the absence of any errors, represented by an empty reasons array (Cause.empty).

Fail

The Fail<E> reason represents a failure due to an expected error of type E. A Cause<E> holding only this reason is created with Cause.fail.

Die

The Die reason indicates a failure resulting from a defect, which is an unexpected or unintended error. A Cause holding only this reason is created with Cause.die.

Interrupt

The Interrupt reason represents a failure due to Fiber interruption and contains the numeric id (number | undefined) of the interrupted Fiber. A Cause holding only this reason is created with Cause.interrupt.

Combining Causes

Cause<E> stores its failure reasons in a flat reasons array. Reasons that occurred sequentially and reasons that occurred concurrently use the same representation. Use Cause.combine to merge two causes into one.

Example (Combining Multiple Failures into One Cause)

1
import { Cause } from "effect"
2

3
const combined = Cause.combine(Cause.fail("Oh no!"), Cause.die("Boom!"))
4

5
combined.reasons.map((reason) => reason._tag) // => ["Fail", "Die"]

Retrieving the Cause of an Effect

To retrieve the cause of a failed effect, use Effect.exit and inspect the cause field of a Failure. This allows you to inspect or handle the exact reason behind the failure.

Example (Retrieving and Inspecting a Failure Cause)

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

3
const program = Effect.gen(function* () {
4
  const exit = yield* Effect.exit(Effect.fail("Oh no!"))
5
  if (Exit.isFailure(exit)) {
6
    console.log(exit.cause)
7
    exit.cause // => Cause.fail("Oh no!")
8
  }
9
})
10

11
await Effect.runPromise(program)

Guards

To determine what happened inside a Cause, the Cause module provides two kinds of guards: cause-level predicates that check whether a Cause contains a certain kind of reason, and reason-level guards that narrow an individual entry of cause.reasons.

• Cause.hasFails: Checks if the cause contains at least one expected failure.
• Cause.hasDies: Checks if the cause contains at least one unexpected defect.
• Cause.hasInterrupts: Checks if the cause contains at least one fiber interruption.
• Cause.hasInterruptsOnly: Checks if every reason in the cause is an interruption.
• Cause.isFailReason: Narrows a Reason to Fail.
• Cause.isDieReason: Narrows a Reason to Die.
• Cause.isInterruptReason: Narrows a Reason to Interrupt.

An empty cause (no errors) is checked with cause.reasons.length === 0; there is no dedicated isEmpty function.

Example (Using Guards to Identify Reason Types)

1
import { Cause } from "effect"
2

3
const cause = Cause.fail(new Error("my message"))
4

5
for (const reason of cause.reasons) {
6
  if (Cause.isFailReason(reason)) {
7
    console.log(reason.error.message)
8
    reason.error.message // => "my message"
9
  }
10
}

These guards allow you to accurately identify the reasons behind a Cause, making it easier to handle various error cases in your code. Whether dealing with expected failures, unexpected defects, or interruptions, these guards provide a clear method for assessing and managing error scenarios.

Formatting Reasons

To respond to specific error scenarios with custom behavior, iterate cause.reasons and switch on each reason’s _tag.

Example (Formatting Each Reason in a Cause)

1
import { Cause } from "effect"
2

3
const cause = Cause.combine(
4
  Cause.fail(new Error("my fail message")),
5
  Cause.die("my die message"),
6
)
7

8
const formatted = cause.reasons
9
  .map((reason) => {
10
    switch (reason._tag) {
11
      case "Fail":
12
        return `(error: ${reason.error.message})`
13
      case "Die":
14
        return `(defect: ${reason.defect})`
15
      case "Interrupt":
16
        return `(fiberId: ${reason.fiberId})`
17
    }
18
  })
19
  .join(", ")
20

21
formatted // => "(error: my fail message), (defect: my die message)"

Pretty Printing

Clear and readable error messages are key for effective debugging. The Cause.pretty function helps by formatting error messages in a structured way, making it easier to understand failure details.

Example (Using Cause.pretty for Readable Error Messages)

1
import { Cause } from "effect"
2

3
console.log(Cause.pretty(Cause.empty))
4
/*
5
Output:
6
(empty string)
7
*/
8
Cause.pretty(Cause.empty) // => ""
9

10
console.log(Cause.pretty(Cause.fail(new Error("my fail message"))))
11
/*
12
Output:
13
Error: my fail message
14
    ...stack trace...
15
*/
16
Cause.pretty(Cause.fail(new Error("my fail message"))).split("\n")[0] // => "Error: my fail message"
17

18
console.log(Cause.pretty(Cause.die("my die message")))
19
/*
20
Output:
21
Error: my die message
22
    ...stack trace...
23
*/
24
Cause.pretty(Cause.die("my die message")).split("\n")[0] // => "Error: my die message"
25

26
console.log(Cause.pretty(Cause.interrupt(1)))
27
Cause.pretty(Cause.interrupt(1)) // => "InterruptError: All fibers interrupted without error {\n  [cause]: InterruptCause: The fiber was interrupted by:\n      at fiber (#1)\n}"
28

29
console.log(
30
  Cause.pretty(Cause.combine(Cause.fail("fail1"), Cause.fail("fail2"))),
31
)
32
/*
33
Output:
34
Error: fail1
35
    ...stack trace...
36
Error: fail2
37
    ...stack trace...
38
*/
39
Cause.pretty(Cause.combine(Cause.fail("fail1"), Cause.fail("fail2")))
40
  .split("\n")
41
  .filter((line) => line.startsWith("Error:")) // => ["Error: fail1", "Error: fail2"]

Retrieval of Failures and Defects

Filter cause.reasons with Cause.isFailReason and Cause.isDieReason to inspect only the expected errors or unexpected defects that occurred.

Example (Extracting Failures and Defects from a Cause)

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

3
const program = Effect.gen(function* () {
4
  const exit = yield* Effect.exit(
5
    Effect.all([
6
      Effect.fail("error 1"),
7
      Effect.die("defect"),
8
      Effect.fail("error 2"),
9
    ]),
10
  )
11
  if (Exit.isFailure(exit)) {
12
    console.log(
13
      exit.cause.reasons
14
        .filter(Cause.isFailReason)
15
        .map((reason) => reason.error),
16
    )
17
    exit.cause.reasons.filter(Cause.isFailReason).map((reason) => reason.error) // => ["error 1"]
18
    console.log(
19
      exit.cause.reasons
20
        .filter(Cause.isDieReason)
21
        .map((reason) => reason.defect),
22
    )
23
    exit.cause.reasons.filter(Cause.isDieReason).map((reason) => reason.defect) // => []
24
  }
25
})
26

27
await Effect.runPromise(program)