Expected Errors

Expected errors are represented in the error channel of Effect:

         ┌─── Success type
         │        ┌─── Error type
         │        │      ┌─── Requirements
         ▼        ▼      ▼
Effect<Success, Error, Requirements>

Because the error type is explicit, callers can see which failures are possible and decide which ones to recover from.

Creating Expected Errors

Effect.fail(error) creates an Effect that fails with error. Use Effect.failSync when constructing the error should be deferred until the Effect runs.

Example (Creating a Typed Failure)

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

3
class UserNotFound extends Data.TaggedError("UserNotFound")<{
4
  readonly id: string
5
}> {}
6

7
const findUser = (id: string): Effect.Effect<string, UserNotFound> =>
8
  id === "1" ? Effect.succeed("Alice") : Effect.fail(new UserNotFound({ id }))
9

10
Effect.runSync(Effect.flip(findUser("2")))._tag // => "UserNotFound"

Errors built with Data.Error or Data.TaggedError are also yieldable directly inside Effect.gen. See Yieldable Errors.

Tracking Multiple Error Types

When effects with different error types are composed, Effect tracks their union.

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

3
class InvalidInput extends Data.TaggedError("InvalidInput")<{}> {}
4
class UserNotFound extends Data.TaggedError("UserNotFound")<{}> {}
5

6
declare const validate: Effect.Effect<string, InvalidInput>
7
declare const loadUser: (id: string) => Effect.Effect<string, UserNotFound>
8

9
// Effect<string, InvalidInput | UserNotFound>
10
const program = Effect.gen(function* () {
11
  const id = yield* validate
12
  return yield* loadUser(id)
13
})

Sequential composition short-circuits on the first failure. Operations after the failure are not evaluated.

Exposing Errors as Values

Sometimes the caller needs to inspect both outcomes without recovering into another Effect.

result

Effect.result moves the typed error into a Result in the success channel:

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

Example (Inspecting a Result)

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

3
const result = Effect.runSync(Effect.result(Effect.fail("unavailable")))
4

5
Result.match(result, {
6
  onFailure: (error) => `failure: ${error}`,
7
  onSuccess: (value) => `success: ${value}`,
8
}) // => "failure: unavailable"

Effect.result handles typed failures only. Defects and interruptions remain failures of the fiber.

option

Effect.option discards the error value, returning Option.some(value) on success and Option.none() on a typed failure.

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

3
Effect.runSync(Effect.option(Effect.succeed(1))) // => Option.some(1)
4
Effect.runSync(Effect.option(Effect.fail("unavailable"))) // => Option.none()

Use result when the error value matters and option only when every typed failure means absence.

Catching Every Typed Error

Effect.catch handles every typed error with a recovery Effect. It does not catch defects or interruptions.

Example (Recovering from Every Typed Error)

1
import { Effect } from "effect"
2

3
const program = Effect.fail("unavailable").pipe(
4
  Effect.catch((error) => Effect.succeed(`recovered: ${error}`)),
5
)
6

7
Effect.runSync(program) // => "recovered: unavailable"

When the handler cannot fail, Effect.catchEager is an eager optimization for recovery Effects that can be evaluated immediately.

Use Effect.catchCause when the handler needs the complete failure cause.

Catching Selected Errors

Selective catch operators preserve all unmatched errors in the error channel.

catchTag

Effect.catchTag handles one member of a tagged error union and removes that member from the resulting error type.

Example (Catching One Tagged Error)

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

3
class NetworkError extends Data.TaggedError("NetworkError")<{
4
  readonly status: number
5
}> {}
6

7
class ValidationError extends Data.TaggedError("ValidationError")<{
8
  readonly field: string
9
}> {}
10

11
const request: Effect.Effect<string, NetworkError | ValidationError> =
12
  Effect.fail(new NetworkError({ status: 503 }))
13

14
// Effect<string, ValidationError>
15
const recovered = request.pipe(
16
  Effect.catchTag("NetworkError", (error) =>
17
    Effect.succeed(`cached after ${error.status}`),
18
  ),
19
)
20

21
Effect.runSync(recovered) // => "cached after 503"

catchTag also accepts a non-empty array of tags when several tagged errors share one handler.

catchTags

Effect.catchTags handles several tagged errors with a table of tag-specific handlers.

Example (Catching Several Tagged Errors)

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

3
class NetworkError extends Data.TaggedError("NetworkError")<{
4
  readonly status: number
5
}> {}
6

7
class ValidationError extends Data.TaggedError("ValidationError")<{
8
  readonly field: string
9
}> {}
10

11
const request: Effect.Effect<string, NetworkError | ValidationError> =
12
  Effect.fail(new ValidationError({ field: "email" }))
13

14
const recovered = request.pipe(
15
  Effect.catchTags({
16
    NetworkError: (error) => Effect.succeed(`network: ${error.status}`),
17
    ValidationError: (error) => Effect.succeed(`invalid: ${error.field}`),
18
  }),
19
)
20

21
Effect.runSync(recovered) // => "invalid: email"

catchIf

Effect.catchIf selects errors with a predicate or type guard.

1
import { Effect } from "effect"
2

3
const program = Effect.fail(404).pipe(
4
  Effect.catchIf(
5
    (status) => status === 404,
6
    () => Effect.succeed("not found"),
7
  ),
8
)
9

10
Effect.runSync(program) // => "not found"

catchFilter

Effect.catchFilter uses the Filter module for reusable or composable selection logic. A narrowing filter also removes the handled subtype from the error channel.

Example (Catching with a Filter)

1
import { Data, Effect, Filter } from "effect"
2

3
class NetworkError extends Data.TaggedError("NetworkError")<{}> {}
4
class ValidationError extends Data.TaggedError("ValidationError")<{}> {}
5

6
const task: Effect.Effect<string, NetworkError | ValidationError> = Effect.fail(
7
  new NetworkError(),
8
)
9

10
const program = task.pipe(
11
  Effect.catchFilter(Filter.tagged("NetworkError"), () =>
12
    Effect.succeed("using cache"),
13
  ),
14
)
15

16
Effect.runSync(program) // => "using cache"

Catching Nested Error Reasons

Some tagged errors contain another tagged error in a readonly reason field. Effect.catchReason handles one nested reason while keeping the parent error type for unmatched reasons; Effect.catchReasons handles several.

Example (Catching a Nested Reason)

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

3
class RateLimitError extends Data.TaggedError("RateLimitError")<{
4
  readonly retryAfter: number
5
}> {}
6

7
class QuotaExceededError extends Data.TaggedError("QuotaExceededError")<{}> {}
8

9
class ApiError extends Data.TaggedError("ApiError")<{
10
  readonly reason: RateLimitError | QuotaExceededError
11
}> {}
12

13
const request: Effect.Effect<string, ApiError> = Effect.fail(
14
  new ApiError({ reason: new RateLimitError({ retryAfter: 30 }) }),
15
)
16

17
const program = request.pipe(
18
  Effect.catchReason("ApiError", "RateLimitError", (reason) =>
19
    Effect.succeed(`retry after ${reason.retryAfter}s`),
20
  ),
21
)
22

23
Effect.runSync(program) // => "retry after 30s"

Use Effect.unwrapReason(errorTag) when the nested reasons should replace the parent error in the error channel instead of being handled immediately.