Extract Failures and Defects from a Cause

Guideline

When you catch with Effect.catchAllCause, use Cause.failures(cause) to get expected typed errors and Cause.defects(cause) to get unexpected defects. Handle them differently: recover or retry failures; log and escalate defects.

Rationale

Failures are part of your domain model (e.g., UserNotFound, ValidationError). Defects are bugs or unhandled exceptions. Extracting them lets you log defects for debugging while treating failures as recoverable business logic.

Good Example

import { Effect, Cause } from "effect"

const program = Effect.die("unexpected bug").pipe(
  Effect.catchAllCause((cause) =>
    Effect.gen(function* () {
      const defects = Cause.defects(cause)
      const failures = Cause.failures(cause)
      yield* Effect.sync(() => {
        console.log("Defects:", defects)
        console.log("Failures:", failures)
      })
      return "recovered"
    })
  )
)

Effect.runPromise(program)

Explanation: Cause.defects and Cause.failures extract the underlying values. Use them to decide: log defects, recover from failures, or return a fallback.

Anti-Pattern

Treating all errors the same, or using Effect.catchAll (without Cause) and losing the ability to distinguish failures from defects.