Unexpected Errors

Unexpected errors, or defects, indicate bugs, violated invariants, or failures outside the program’s expected domain. They are retained in the runtime Cause, but do not appear in the typed error channel.

Defects normally should be reported and allowed to terminate the affected fiber. Recover from them only at boundaries where continuing is explicitly safe.

Creating a Defect

Effect.die(defect) creates an Effect that terminates with the supplied defect. Its typed error channel is never.

Example (Terminating on an Impossible Input)

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

3
const divide = (a: number, b: number) =>
4
  b === 0
5
    ? Effect.die(new Error("Cannot divide by zero"))
6
    : Effect.succeed(a / b)
7

8
const exit = Effect.runSyncExit(divide(1, 0))
9

10
Exit.isFailure(exit) && exit.cause.reasons[0]?._tag // => "Die"

Pass a string or, preferably, an Error with a useful message to Effect.die.

Exceptions thrown while evaluating Effect callbacks such as Effect.sync are also represented as defects.

Converting Typed Errors to Defects

Effect.orDie converts every typed failure into a defect and removes the typed error channel.

Example (Treating a Failure as Unrecoverable)

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

3
const program = Effect.fail(new Error("Invalid startup configuration")).pipe(
4
  Effect.orDie,
5
)
6

7
const exit = Effect.runSyncExit(program)
8

9
Exit.isFailure(exit) && exit.cause.reasons[0]?._tag // => "Die"

To customize the defect, transform the typed error first with Effect.mapError and then apply Effect.orDie.

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

3
const program = Effect.fail("missing token").pipe(
4
  Effect.mapError((message) => new Error(`Startup failed: ${message}`)),
5
  Effect.orDie,
6
)
7

8
const exit = Effect.runSyncExit(program)
9

10
const reason = Exit.isFailure(exit) ? exit.cause.reasons[0] : undefined
11
const message =
12
  reason !== undefined &&
13
  Cause.isDieReason(reason) &&
14
  Predicate.isError(reason.defect)
15
    ? reason.defect.message
16
    : undefined
17

18
message // => "Startup failed: missing token"

Inspecting the Complete Exit

Effect.exit moves the complete outcome into the success channel:

Effect<A, E, R> -> Effect<Exit<A, E>, never, R>

Unlike Effect.result, an Exit preserves the complete Cause, including defects and interruptions.

Example (Inspecting a Defect with Exit)

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

3
const exit = Effect.runSync(Effect.exit(Effect.die("boom")))
4

5
const hasDefect = Exit.isFailure(exit) && Cause.hasDies(exit.cause)
6

7
hasDefect // => true

This is useful at application boundaries, in tests, and when integrating with APIs that need an explicit value for every outcome.

catchDefect

Effect.catchDefect handles defects only. Typed failures and interruptions are left unchanged.

Example (Recovering from a Defect)

1
import { Effect, Predicate } from "effect"
2

3
const program = Effect.die(new Error("plugin crashed")).pipe(
4
  Effect.catchDefect((defect) =>
5
    Predicate.isError(defect)
6
      ? Effect.succeed(`disabled plugin: ${defect.message}`)
7
      : Effect.die(defect),
8
  ),
9
)
10

11
Effect.runSync(program) // => "disabled plugin: plugin crashed"

catchCause

Effect.catchCause handles the complete Cause, including typed failures, defects, interruptions, and multiple reasons.

Example (Recovering Based on the Cause)

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

3
const program = Effect.die("boom").pipe(
4
  Effect.catchCause((cause) =>
5
    Cause.hasDies(cause)
6
      ? Effect.succeed("recovered at the boundary")
7
      : Effect.failCause(cause),
8
  ),
9
)
10

11
Effect.runSync(program) // => "recovered at the boundary"

Prefer typed recovery operators such as Effect.catch and Effect.catchTag for domain errors. Use catchDefect or catchCause only where recovering from unexpected failures is intentional and safe.