Error Management


Errors are a common part of programming, and they can happen for various reasons, such as failures, defects, fiber interruptions, or even a combination of these factors. In this guide, we'll explore how to use the Effect.sandbox function to isolate and understand the causes of errors in your code.


The Effect.sandbox function is a valuable tool that allows you to encapsulate all the potential causes of an error in an effect. It exposes the full cause of an effect, whether it's due to a failure, defect, fiber interruption, or a combination of these factors.

Here's the signature of the Effect.sandbox function:

sandbox: Effect<R, E, A> -> Effect<R, Cause<E>, A>

In simple terms, it takes an effect Effect<R, E, A> and transforms it into an effect Effect<R, Cause<E>, A> where the error channel now contains a detailed cause of the error.

By using the Effect.sandbox function, you gain access to the underlying causes of exceptional effects. These causes are represented as a type of Cause<E> and are available in the error channel of the Effect data type.

Once you have exposed the causes, you can utilize standard error-handling operators like Effect.catchAll and Effect.catchTags to handle errors more effectively. These operators allow you to respond to specific error conditions.

Let's walk through an example to illustrate how error sandboxing works:

import { Effect, Console } from "effect"
// $ExpectType Effect<never, string, string>
const effect ="Oh uh!").pipe("primary result"))
// $ExpectType Effect<never, Cause<string>, string>
const sandboxed = Effect.sandbox(effect)
// $ExpectType Effect<never, Empty | Sequential<string> | Parallel<string>, string>
const program = Effect.catchTags(sandboxed, {
  Die: (cause) =>
    Console.log(`Caught a defect: ${cause.defect}`).pipe("fallback result on defect")
  Interrupt: (cause) =>
    Console.log(`Caught a defect: ${cause.fiberId}`).pipe("fallback result on fiber interruption")
  Fail: (cause) =>
    Console.log(`Caught a defect: ${cause.error}`).pipe("fallback result on failure")
// $ExpectType Effect<never, string, string>
const main = Effect.unsandbox(program)
Caught a defect: Oh uh!
fallback result on failure

In this example, we expose the full cause of an effect using Effect.sandbox. Then, we handle specific error conditions using Effect.catchTags. Finally, if needed, we can undo the sandboxing operation with Effect.unsandbox.