04 - Error Types: Making Errors First-Class

Previous · Next

The E channel only pays off if the compiler can tell variants apart. A string or a bare Error carries no shape; the type system cannot narrow on it.

This step covers the discriminated tagged-error pattern that makes recovery operators (step 09) precise.

What you’ll work through

index.test.ts contains four beats. The first two introduce the two ways to write a tagged error — Data.TaggedError and a manual _tag class.

The third constructs an error union; the fourth narrows on _tag inside a switch and reads variant-specific fields.

By the end you should be able to define a tagged error, place it in E, and narrow on _tag without casts.

Mental Model

A tagged union uses a literal _tag field to distinguish members. Once the discriminant is checked, the compiler narrows to the specific variant, its fields become accessible without casts and a switch produces an exhaustiveness error if a case is missing.

1
Effect<User, NotFoundError | NetworkError>
2
                     │              │
3
                     ▼              ▼
4
             _tag: "NotFound"   _tag: "Network"
5
             { resource, id }   { url, status }
6

7
switch (error._tag) {
8
  case "NotFound":  error.resource  ✓   error.url       ✗
9
  case "Network":   error.status    ✓   error.resource  ✗
10
}

`Data.TaggedError`

Creates a class whose instances carry an auto-set _tag, structural equality, and a single object-shaped constructor. This is the canonical error shape in Effect code.

1
import { Data } from "effect"
2

3
class ParseError extends Data.TaggedError("ParseError")<{
4
  readonly input: string
5
  readonly reason: string
6
}> {}
7

8
class NetworkError extends Data.TaggedError("NetworkError")<{
9
  readonly url: string
10
  readonly status: number
11
}> {}
12

13
const err = new ParseError({ input: "bad", reason: "not a number" })
14
//          ┌─── _tag: "ParseError", input: string, reason: string
15
err._tag    // "ParseError"
16
err.input   // "bad"

Details

Data.TaggedError extends Effect.YieldableError, so an instance is itself a failing Effect and can be yield*-ed inside Effect.gen. The _tag is a literal type, not widened to string, narrowing on it works without as const.

When to Use

For every domain error in an Effect program. The constructor pattern (named fields) scales to errors with several pieces of context.

@see catchTag and catchTags in step 09 for the recovery operators that consume the _tag discriminant.

Your turn construct a `ParseError` with `{ input, reason }` and place it in the E channel via `Effect.fail`.

Manual `_tag`

When you cannot import from effect (libraries, shared types, generated code), the same shape can be written by hand.

1
class ValidationError extends Error {
2
  readonly _tag = "ValidationError" as const
3
  constructor(readonly field: string, message: string) {
4
    super(message)
5
  }
6
}

The as const is required. Without it the inferred type is string, and narrowing on _tag stops working.

> still compiles, but `catchTag` and `switch` exhaustiveness silently stop > working. `Data.TaggedError` does this for you; the manual form does not.

When to Use

In code that should not depend on effect, or when extending an existing exception class hierarchy.

Your turn instantiate `ValidationError` with a field name and message so the manual `_tag` is preserved through `Effect.fail`.

Error Unions

A function with multiple failure modes lists every error in E. The compiler tracks the union through the entire pipeline.

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

3
class NotFoundError extends Data.TaggedError("NotFoundError")<{ id: string }> {}
4
class NetworkError extends Data.TaggedError("NetworkError")<{ status: number }> {}
5

6
//      ┌─── Effect<{ name: string }, NotFoundError | NetworkError, never>
7
//      ▼
8
const fetchUser = (
9
  id: string,
10
): Effect.Effect<{ name: string }, NotFoundError | NetworkError> => {
11
  if (id === "bad-url") return Effect.fail(new NetworkError({ status: 500 }))
12
  if (id === "missing") return Effect.fail(new NotFoundError({ id }))
13
  return Effect.succeed({ name: "Alice" })
14
}

Every caller can see both failure modes from the signature. Recovery operators (step 09) remove variants from the union one at a time, and the type narrows accordingly.

Your turn pick the right variant (`NotFoundError` or `NetworkError`) for each rejection branch.

Narrowing on `_tag`

The whole point of the tag is that the compiler narrows inside each case.

1
const exit = await Effect.runPromiseExit(fetchUser("missing"))
2
if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
3
  const error = exit.cause.reasons[0].error
4
  // error: NotFoundError | NetworkError
5
  switch (error._tag) {
6
    case "NotFoundError":
7
      error.id      // ✓ string
8
      break
9
    case "NetworkError":
10
      error.status  // ✓ number
11
      break
12
    // Missing a case is a TypeScript error when E is a closed union.
13
  }
14
}

Your turn switch on `error._tag` and read the right field inside each branch. A missed case is a TypeScript error — the test relies on exhaustive narrowing.

`_tag` must match exactly

catchTag matches on the literal _tag string. A single-character difference means the handler never fires and the error stays in E — and because the type for the tag is a string literal, a typo in the catcher will still compile (especially if you cast).

1
// _tag is "ValidationError" — note the exact spelling.
2
class ValidationError extends Error {
3
  readonly _tag = "ValidationError" as const
4
  constructor(readonly field: string, message: string) {
5
    super(message)
6
  }
7
}
8

9
// ✗ Typo: "Validation" never equals "ValidationError" — the error escapes.
10
Effect.fail(new ValidationError("email", "bad")).pipe(
11
  Effect.catch((err) =>
12
    (err._tag as string) === "Validation"
13
      ? Effect.succeed("handled")
14
      : Effect.fail(err),
15
  ),
16
)
17
// Exit: Failure(ValidationError)
18

19
// ✓ Exact match — catchTag routes the error to the handler.
20
Effect.fail(new ValidationError("email", "bad")).pipe(
21
  Effect.catchTag("ValidationError", () => Effect.succeed("handled")),
22
)
23
// Exit: Success("handled")

> Tools that rename a class do not rename string literals, and a misspelled > tag inside `catchTag` is the kind of bug that ships silently. Prefer > `Data.TaggedError` (it removes the manual `as const`) and let your editor > autocomplete the catcher from the class name.

Your turn read the "wrong tag string" assertion and confirm it's a failure exit. Then complete the second test by replacing the stub with the correct `catchTag("ValidationError", ...)` call.

`Data.TaggedError` vs Manual

Feature	Manual `extends Error`	`Data.TaggedError`
`_tag` discriminant	manual (`readonly _tag = "X" as const`)	automatic
Structural equality	no	yes (via `Equal`)
Constructor	`new E(arg1, arg2)`	`new E({ field1, field2 })`
Yieldable in `Effect.gen`	no	yes
Recommended for Effect code	no	yes

Rules of thumb

One tagged error per failure mode. Discriminate by _tag, not by message. The compiler narrows _tag exhaustively; it can’t narrow strings.
Error fields are values, not exceptions. Keep them small, readonly, and structurally meaningful — they will be serialized, logged, and matched on.
Data.TaggedError is the canonical form. It plays directly with catchTag, Match.tag, and Effect.catchTags.

Common Pitfalls

1, Forgetting as const. Without it the manual _tag widens to string and catchTag cannot narrow. Data.TaggedError handles this automatically.

2, string errors. Effect.fail("oops") gives Effect<never, string>. Strings cannot be discriminated; use a tagged class as soon as more than one error mode exists.

3, Plain Error with catchTag. Effect.catchTag requires a _tag field. A bare Error will not type-check.

4, Partial handling. Catching one variant of a union leaves the others in E. That is the desired behavior, the type tells you what remains.

and place it in `E` via `Effect.fail`. - [ ] Complete `manual-tag`: write the `_tag` by hand with `as const`. Remove `as const` once to see narrowing break, then restore it. - [ ] Complete `error-unions`: pick the variant that matches each rejection. - [ ] Complete `narrow-on-tag`: switch on `_tag` and read the variant-specific field. Confirm an unreachable `default` is a type error. - [ ] Note how this pattern primes `catchTag` in step 09 — the `_tag` is the handle.

The full test suite

The index.test.ts for this lesson, verbatim from steps/04-error-types/.

1
import { it, expect } from "vite-plus/test"
2
import { Effect, Exit, Data } from "effect"
3

4
// =============================================================================
5
// 05 - Error Types: Making Errors First-Class
6
// =============================================================================
7
//
8
// Data.TaggedError creates a class with an auto-set _tag, structural equality,
9
// and an object-shaped constructor. Manual _tag is supported as a fallback when
10
// `effect` cannot be imported. The discriminant is what makes catchTag work.
11

12
class ValidationError extends Error {
13
  readonly _tag = "ValidationError" as const
14
  constructor(readonly field: string, message: string) {
15
    super(message)
16
  }
17
}
18

19
class ParseError extends Data.TaggedError("ParseError")<{
20
  readonly input: string
21
  readonly reason: string
22
}> {}
23

24
class NotFoundError extends Data.TaggedError("NotFoundError")<{
25
  readonly id: string
26
}> {}
27

28
class NetworkError extends Data.TaggedError("NetworkError")<{
29
  readonly status: number
30
}> {}
31

32
// @beat
33
//   id: manual-tag
34
//   shape: one-todo
35
//   title: Discriminate with a manual _tag
36
//   teaches: A literal `_tag` with `as const` makes a plain class discriminable; without `as const` it widens to string.
37
//   hint: instantiate ValidationError with the field name and a message
38
it("carries typed fields accessible after instanceof narrowing", () => {
39
  const program = Effect.fail(
40
    /* @stub */ new ValidationError("email", "Invalid email format") /* @end */,
41
  )
42
  const exit = Effect.runSyncExit(program)
43

44
  expect(Exit.isFailure(exit)).toBe(true)
45
  if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
46
    expect(exit.cause.reasons[0].error._tag).toBe("ValidationError")
47
    if (exit.cause.reasons[0].error instanceof ValidationError) {
48
      expect(exit.cause.reasons[0].error.field).toBe("email")
49
      expect(exit.cause.reasons[0].error.message).toBe("Invalid email format")
50
    }
51
  }
52
})
53
// @end-beat
54

55
// @beat
56
//   id: data-tagged-error
57
//   shape: multi-todo
58
//   title: Build domain errors with Data.TaggedError
59
//   teaches: Data.TaggedError auto-sets the `_tag`, gives an object-shaped constructor, and yields an Effect-yieldable error.
60
//   hint: construct ParseError with { input, reason } and let `_tag` be set by the class
61
it("auto-sets _tag and exposes fields directly", () => {
62
  const error = /* @stub */ new ParseError({ input: "bad", reason: "test" }) /* @end */
63
  expect(error._tag).toBe("ParseError")
64
  expect(error.input).toBe("bad")
65
  expect(error.reason).toBe("test")
66
})
67

68
it("places a structured error in the E channel", () => {
69
  const program = Effect.fail(
70
    /* @stub */ new ParseError({ input: "not json", reason: "Invalid JSON syntax" }) /* @end */,
71
  )
72
  const exit = Effect.runSyncExit(program)
73

74
  if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
75
    const error = exit.cause.reasons[0].error
76
    expect(error._tag).toBe("ParseError")
77
    expect(error.input).toBe("not json")
78
    expect(error.reason).toBe("Invalid JSON syntax")
79
  }
80
})
81
// @end-beat
82

83
// @beat
84
//   id: error-unions
85
//   shape: multi-todo
86
//   title: List every failure in an error union
87
//   teaches: A function with multiple failure modes lists each tagged error in E; the compiler tracks the union through the pipeline.
88
//   hint: choose the variant whose tag matches the case the test is exercising
89
it("succeeds on the happy path", () => {
90
  //      ┌─── Effect<{ name: string }, NotFoundError | NetworkError, never>
91
  //      ▼
92
  const fetchUser = (
93
    id: string,
94
  ): Effect.Effect<{ name: string }, NotFoundError | NetworkError> => {
95
    if (id === "bad-url") return Effect.fail(new NetworkError({ status: 500 }))
96
    if (id === "missing") return Effect.fail(new NotFoundError({ id }))
97
    return Effect.succeed({ name: "Alice" })
98
  }
99

100
  expect(Effect.runSync(fetchUser("123"))).toEqual({ name: "Alice" })
101
})
102

103
it("places NotFoundError in E", () => {
104
  const fetchUser = (
105
    id: string,
106
  ): Effect.Effect<{ name: string }, NotFoundError | NetworkError> => {
107
    if (id === "bad-url") return Effect.fail(new NetworkError({ status: 500 }))
108
    if (id === "missing")
109
      return /* @stub */ Effect.fail(new NotFoundError({ id })) /* @end */
110
    return Effect.succeed({ name: "Alice" })
111
  }
112

113
  const exit = Effect.runSyncExit(fetchUser("missing"))
114
  if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
115
    expect(exit.cause.reasons[0].error._tag).toBe("NotFoundError")
116
  }
117
})
118

119
it("places NetworkError in E", () => {
120
  const fetchUser = (
121
    id: string,
122
  ): Effect.Effect<{ name: string }, NotFoundError | NetworkError> => {
123
    if (id === "bad-url")
124
      return /* @stub */ Effect.fail(new NetworkError({ status: 500 })) /* @end */
125
    if (id === "missing") return Effect.fail(new NotFoundError({ id }))
126
    return Effect.succeed({ name: "Alice" })
127
  }
128

129
  const exit = Effect.runSyncExit(fetchUser("bad-url"))
130
  if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
131
    expect(exit.cause.reasons[0].error._tag).toBe("NetworkError")
132
  }
133
})
134
// @end-beat
135

136
// @beat
137
//   id: narrow-on-tag
138
//   shape: multi-todo
139
//   title: Narrow on `_tag`
140
//   teaches: A switch (or if-chain) on `_tag` narrows to the specific variant; each branch sees only that variant's fields.
141
//   hint: switch on `error._tag` and read the field for that variant inside the case
142
it("exposes the specific variant's fields inside each case", () => {
143
  class DivByZero extends Data.TaggedError("DivByZero")<{ readonly op: string }> {}
144
  class Overflow extends Data.TaggedError("Overflow")<{ readonly value: number }> {}
145

146
  const safeDivide = (
147
    a: number,
148
    b: number,
149
  ): Effect.Effect<number, DivByZero | Overflow> => {
150
    if (b === 0) return Effect.fail(new DivByZero({ op: `${a}/${b}` }))
151
    if (a > 1e15) return Effect.fail(new Overflow({ value: a }))
152
    return Effect.succeed(a / b)
153
  }
154

155
  const exit = Effect.runSyncExit(safeDivide(10, 0))
156
  if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
157
    const error = exit.cause.reasons[0].error
158
    /* @stub */ switch (error._tag) {
159
      case "DivByZero":
160
        expect(error.op).toBe("10/0")
161
        break
162
      case "Overflow":
163
        throw new Error("unexpected Overflow")
164
    } /* @end */
165
  }
166
})
167

168
it("narrows independently for each member of the union", () => {
169
  class TooShort extends Data.TaggedError("TooShort")<{ readonly min: number }> {}
170
  class TooLong extends Data.TaggedError("TooLong")<{ readonly max: number }> {}
171

172
  const validateLength = (
173
    s: string,
174
    min: number,
175
    max: number,
176
  ): Effect.Effect<string, TooShort | TooLong> => {
177
    if (s.length < min) return Effect.fail(new TooShort({ min }))
178
    if (s.length > max) return Effect.fail(new TooLong({ max }))
179
    return Effect.succeed(s)
180
  }
181

182
  const shortExit = Effect.runSyncExit(validateLength("hi", 5, 10))
183
  if (Exit.isFailure(shortExit) && shortExit.cause.reasons[0]?._tag === "Fail") {
184
    const err = shortExit.cause.reasons[0].error
185
    if (/* @stub */ err._tag === "TooShort" /* @end */) {
186
      expect(err.min).toBe(5)
187
    }
188
  }
189

190
  const longExit = Effect.runSyncExit(validateLength("x".repeat(20), 5, 10))
191
  if (Exit.isFailure(longExit) && longExit.cause.reasons[0]?._tag === "Fail") {
192
    const err = longExit.cause.reasons[0].error
193
    if (/* @stub */ err._tag === "TooLong" /* @end */) {
194
      expect(err.max).toBe(10)
195
    }
196
  }
197
})
198
// @end-beat
199

200
// @beat
201
//   id: tag-matters
202
//   shape: multi-todo
203
//   title: _tag must match exactly
204
//   teaches: catchTag matches on the literal _tag string; a single character difference means the handler never fires and the error stays in E.
205
//   hint: the string you pass to catchTag must equal the _tag field value exactly — compare both sides character for character
206

207
it("a wrong _tag string leaves the error unhandled (read this)", () => {
208
  // ValidationError._tag = "ValidationError"
209
  // The handler below listens for "Validation" — one word short.
210
  // The types still compile because we cast, but the handler never fires.
211
  const program = Effect.fail(new ValidationError("email", "bad input")).pipe(
212
    Effect.catch((err) => {
213
      // Manual _tag check — simulates what catchTag does under the hood
214
      if ((err._tag as string) === "Validation") {
215
        return Effect.succeed("handled")
216
      }
217
      return Effect.fail(err) // typo means we fall through
218
    }),
219
  )
220

221
  const exit = Effect.runSyncExit(program)
222
  expect(Exit.isFailure(exit)).toBe(true) // the error was NOT caught
223
})
224

225
it("the exact _tag string routes the error to the handler", () => {
226
  const program = /* @stub */ Effect.fail(
227
    new ValidationError("email", "bad input"),
228
  ).pipe(
229
    Effect.catchTag("ValidationError", () => Effect.succeed("handled")),
230
  ) /* @end */
231

232
  expect(Effect.runSync(program)).toBe("handled")
233
})
234
// @end-beat

01·02Error Types

04 - Error Types: Making Errors First-Class

What you’ll work through

Mental Model

`Data.TaggedError`

Manual `_tag`

Error Unions

Narrowing on `_tag`

`_tag` must match exactly

`Data.TaggedError` vs Manual

Rules of thumb

Common Pitfalls

See Also

The full test suite

01·02Error Types

04 - Error Types: Making Errors First-Class

What you’ll work through

Mental Model

Data.TaggedError

Manual _tag

Error Unions

Narrowing on _tag

_tag must match exactly

Data.TaggedError vs Manual

Rules of thumb

Common Pitfalls

See Also

The full test suite

`Data.TaggedError`

Manual `_tag`

Narrowing on `_tag`

`_tag` must match exactly

`Data.TaggedError` vs Manual