1# Error Handling: `catch*` Renamings
2
3The `catch` combinators on `Effect` have been renamed in v4. The general
4pattern: `catchAll*` is shortened to `catch*`, and the `catchSome*` family is
5replaced by `catchFilter` / `catchCauseFilter`.
6
7## Renamings
8
9| v3 | v4 |
10| ------------------------ | ------------------------------ |
11| `Effect.catchAll` | `Effect.catch` |
12| `Effect.catchAllCause` | `Effect.catchCause` |
13| `Effect.catchAllDefect` | `Effect.catchDefect` |
14| `Effect.catchTag` | `Effect.catchTag` (unchanged) |
15| `Effect.catchTags` | `Effect.catchTags` (unchanged) |
16| `Effect.catchIf` | `Effect.catchIf` (unchanged) |
17| `Effect.catchSome` | `Effect.catchFilter` |
18| `Effect.catchSomeCause` | `Effect.catchCauseFilter` |
19| `Effect.catchSomeDefect` | Removed |
20
21## `Effect.catchAll` → `Effect.catch`
22
23**v3**
24
25```ts
26import { Effect } from "effect"
27
28const program = Effect.fail("error").pipe(
29 Effect.catchAll((error) => Effect.succeed(`recovered: ${error}`))
30)
31```
32
33**v4**
34
35```ts
36import { Effect } from "effect"
37
38const program = Effect.fail("error").pipe(
39 Effect.catch((error) => Effect.succeed(`recovered: ${error}`))
40)
41```
42
43## `Effect.catchAllCause` → `Effect.catchCause`
44
45**v3**
46
47```ts
48import { Effect } from "effect"
49
50const program = Effect.die("defect").pipe(
51 Effect.catchAllCause((cause) => Effect.succeed("recovered"))
52)
53```
54
55**v4**
56
57```ts
58import { Cause, Effect } from "effect"
59
60const program = Effect.die("defect").pipe(
61 Effect.catchCause((cause) => Effect.succeed("recovered"))
62)
63```
64
65## `Effect.catchSome` → `Effect.catchFilter`
66
67In v3, `catchSome` took a function returning `Option<Effect>`. In v4,
68`catchFilter` uses the `Filter` module instead.
69
70**v3**
71
72```ts
73import { Effect, Option } from "effect"
74
75const program = Effect.fail(42).pipe(
76 Effect.catchSome((error) =>
77 error === 42
78 ? Option.some(Effect.succeed("caught"))
79 : Option.none()
80 )
81)
82```
83
84**v4**
85
86```ts
87import { Effect, Filter } from "effect"
88
89const program = Effect.fail(42).pipe(
90 Effect.catchFilter(
91 Filter.fromPredicate((error: number) => error === 42),
92 (error) => Effect.succeed("caught")
93 )
94)
95```
96
97## New in v4
98
99- **`Effect.catchReason(errorTag, reasonTag, handler)`** — catches a specific
100 `reason` within a tagged error without removing the parent error from the
101 error channel. Useful for handling nested error causes (e.g. an `AiError`
102 with a `reason: RateLimitError | QuotaExceededError`).
103- **`Effect.catchReasons(errorTag, cases)`** — like `catchReason` but handles
104 multiple reason tags at once via an object of handlers.
105- **`Effect.catchEager(handler)`** — an optimization variant of `catch` that
106 evaluates synchronous recovery effects immediately.