Defining Errors with Schema | Effect Schema

In most applications, errors are not just strings. They carry structured data: an HTTP status code, a missing field name, a failed validation path. If you are already using Effect Schema to validate your data, it makes sense to validate your errors the same way.

Effect Schema provides two APIs for defining error classes whose fields are validated against a schema: Schema.ErrorClass and Schema.TaggedErrorClass. These give you error classes that are:

Validated at construction time. When you create an instance with new, the fields you pass in are checked against the schema. If a field is invalid, you get a clear error immediately, not a silent bug downstream.
Yieldable inside Effect.gen. You can yield* an error instance directly, and it is automatically treated as a failed Effect.
Serializable. Because they are built on schemas, these error classes can be encoded to plain objects and decoded back, which is useful for logging, network transport, or persistence.
Extensible. You can create error hierarchies where a base error class is extended with additional fields.

Schema.ErrorClass

Schema.ErrorClass creates an error class with schema-validated fields. It follows a curried, two-step pattern:

The term “curried” means that instead of calling a function with all its arguments at once, you call it one step at a time. Each call returns a new function that accepts the next argument. So instead of f(a, b), you write f(a)(b). You will see this pattern frequently in Effect.

Call Schema.ErrorClass with an identifier string (this becomes the error’s .name property).
Call the result with a fields object (or a Schema.Struct).

You then use the result as a base class with extends.

1
import { Schema } from "effect";
2

3
class HttpError extends Schema.ErrorClass<HttpError>("HttpError")({
4
  statusCode: Schema.Number,
5
  message: Schema.String,
6
}) {}
7

8
const err = new HttpError({ statusCode: 404, message: "Not Found" });
9

10
console.log(err instanceof Error); // true
11
console.log(err.name); // HttpError
12
console.log(err.statusCode); // 404
13
console.log(err.message); // Not Found

The HttpError class behaves like a normal JavaScript Error (it has .name, .message, .stack), but its fields are validated. If you pass an invalid value, construction fails immediately:

1
import { Schema } from "effect";
2

3
class HttpError extends Schema.ErrorClass<HttpError>("HttpError")({
4
  statusCode: Schema.Number,
5
  message: Schema.String,
6
}) {}
7

8
const badInput: unknown = { statusCode: "oops", message: "Not Found" };
9

10
try {
11
  Schema.decodeUnknownSync(HttpError)(badInput);
12
} catch (error) {
13
  if (error instanceof Error) {
14
    console.log(error.message);
15
  }
16
}

Output:

1
Expected number, got "oops"
2
  at ["statusCode"]

You can also pass a Schema.Struct instead of a plain fields object. This is useful when you want to reuse an existing struct schema:

1
import { Schema } from "effect";
2

3
const ErrorFields = Schema.Struct({
4
  statusCode: Schema.Number,
5
  message: Schema.String,
6
});
7

8
class HttpError extends Schema.ErrorClass<HttpError>("HttpError")(
9
  ErrorFields,
10
) {}
11

12
const err = new HttpError({
13
  statusCode: 500,
14
  message: "Internal Server Error",
15
});
16
console.log(err.statusCode); // 500
17
console.log(err.message); // "Internal Server Error"

Schema.TaggedErrorClass

Schema.TaggedErrorClass builds on Schema.ErrorClass by automatically adding a _tag field to your error class. The _tag field is a literal string that acts as a discriminator, letting you match errors by tag in handlers like Effect.catchTag.

It follows a curried, three-step pattern:

Call Schema.TaggedErrorClass with an optional identifier string. If you omit it, the tag value is used as the identifier.
Call the result with a tag string and a fields object (or a Schema.Struct).
Use the result as a base class with extends.

1
import { Schema } from "effect";
2

3
class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()(
4
  "NotFoundError",
5
  { resource: Schema.String, id: Schema.String },
6
) {}
7

8
const err = new NotFoundError({
9
  resource: "User",
10
  id: "abc-123",
11
});
12

13
console.log(err._tag); // NotFoundError
14
console.log(err.name); // NotFoundError
15
console.log(err.resource); // User
16
console.log(err.id); // abc-123

Default Value for Error Fields

You can provide default values for error fields using Schema.withConstructorDefault. This allows callers to omit certain fields when constructing an error, while still having them present on the instance.

1
import { Option, Schema } from "effect";
2

3
class RateLimitError extends Schema.TaggedErrorClass<RateLimitError>()(
4
  "RateLimitError",
5
  {
6
    endpoint: Schema.String,
7
    retryAfterMs: Schema.Number.pipe(
8
      Schema.optionalKey,
9
      Schema.withConstructorDefault(() => Option.some(60_000)),
10
    ),
11
  },
12
) {}
13

14
// Using the default retry delay
15
const err1 = new RateLimitError({ endpoint: "/api/search" });
16
console.log(err1.endpoint); // "/api/search"
17
console.log(err1.retryAfterMs); // 60000
18

19
// Server told us to wait 5 seconds
20
const err2 = new RateLimitError({
21
  endpoint: "/api/search",
22
  retryAfterMs: 5000,
23
});
24
console.log(err2.retryAfterMs); // 5000

Zero-Field Tagged Errors

Sometimes an error needs no extra data beyond its tag. In this case, you can pass an empty fields object. The constructor argument becomes optional, so you can write new NotFoundError() without passing {}:

1
import { Schema } from "effect";
2

3
class UnauthorizedError extends Schema.TaggedErrorClass<UnauthorizedError>()(
4
  "UnauthorizedError",
5
  {},
6
) {}
7

8
// Both are valid
9
const a = new UnauthorizedError();
10
const b = new UnauthorizedError({});
11

12
console.log(a._tag); // "UnauthorizedError"
13
console.log(b._tag); // "UnauthorizedError"

Custom Identifier

By default, the tag value is used as both the _tag and the error’s .name. If you need a different .name (for example, to namespace your errors), pass an identifier as the first argument:

1
import { Schema } from "effect";
2

3
class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>(
4
  "myapp/NotFoundError",
5
)("NotFoundError", {
6
  resource: Schema.String,
7
}) {}
8

9
const err = new NotFoundError({ resource: "Invoice" });
10

11
console.log(err._tag); // "NotFoundError"
12
console.log(err.name); // "myapp/NotFoundError"

The _tag remains "NotFoundError" (used for matching with Effect.catchTag), while .name is "myapp/NotFoundError" (shown in stack traces and String(err)).

ErrorClass vs TaggedErrorClass

Feature	`ErrorClass`	`TaggedErrorClass`
`_tag` field	Not included	Automatically added as a literal
Identifier	Required (first argument)	Optional (defaults to tag value)
Works with catchTag	No (no `_tag`)	Yes
Constructor fields	Only your defined fields	Your fields + `_tag` (auto-provided)
Base class	`YieldableError`	`YieldableError`

In practice, TaggedErrorClass is the more common choice because Effect’s error-handling combinators (Effect.catchTag, Effect.catchTags) rely on the _tag field to discriminate between error types.

Key Features

Yieldable Errors

Both ErrorClass and TaggedErrorClass produce classes that extend YieldableError. This means you can yield* an error instance directly inside an Effect.gen generator. When you do, the generator short-circuits and the enclosing Effect fails with that error.

1
import { Effect, Schema } from "effect";
2

3
class InvalidAgeError extends Schema.TaggedErrorClass<InvalidAgeError>()(
4
  "InvalidAgeError",
5
  {
6
    age: Schema.Number,
7
    reason: Schema.String,
8
  },
9
) {}
10

11
function validateAge(age: number) {
12
  return Effect.gen(function* () {
13
    if (age < 0) {
14
      // yield* directly on the error instance
15
      yield* new InvalidAgeError({
16
        age,
17
        reason: "Age cannot be negative",
18
      });
19
    }
20

21
    if (age > 150) {
22
      yield* new InvalidAgeError({
23
        age,
24
        reason: "Age exceeds reasonable maximum",
25
      });
26
    }
27

28
    return age;
29
  });
30
}
31

32
// Running with valid input
33
Effect.runPromise(validateAge(25)).then(console.log);
34

35
// Running with invalid input and handling the error
36
const program = validateAge(-5).pipe(
37
  Effect.catchTag("InvalidAgeError", (err) =>
38
    Effect.succeed(`Rejected: ${err.reason} (got ${err.age})`),
39
  ),
40
);
41

42
Effect.runPromise(program).then(console.log);

Output:

1
25
2
Rejected: Age cannot be negative (got -5)

Notice how Effect.catchTag("InvalidAgeError", ...) works seamlessly because InvalidAgeError has a _tag of "InvalidAgeError". The handler receives the fully typed error instance with access to .age and .reason.

Serializable

Because these error classes are built on Schema, they participate fully in the encoding and decoding pipeline. You can encode an error instance to a plain object and decode a plain object back into an error instance. This is useful when you need to serialize errors for logging, send them over the network, or store them.

1
import { Schema } from "effect";
2

3
class ValidationError extends Schema.TaggedErrorClass<ValidationError>()(
4
  "ValidationError",
5
  {
6
    field: Schema.String,
7
    expected: Schema.String,
8
    received: Schema.String,
9
  },
10
) {}
11

12
const encode = Schema.encodeSync(ValidationError);
13
const decode = Schema.decodeUnknownSync(ValidationError);
14

15
// Encoding: error instance -> plain object
16
const err = new ValidationError({
17
  field: "email",
18
  expected: "a valid email address",
19
  received: "not-an-email",
20
});
21

22
const encoded = encode(err);
23
console.log(encoded);
24

25
// Decoding: plain object -> error instance
26
const decoded = decode({
27
  _tag: "ValidationError",
28
  field: "email",
29
  expected: "a valid email address",
30
  received: "not-an-email",
31
});
32

33
console.log(decoded instanceof ValidationError); // true
34
console.log(decoded instanceof Error); // true
35
console.log(decoded._tag); // "ValidationError"
36
console.log(decoded.field); // "email"

Output:

1
{
2
  _tag: 'ValidationError',
3
  field: 'email',
4
  expected: 'a valid email address',
5
  received: 'not-an-email'
6
}
7
true
8
true
9
ValidationError
10
email

When decoding, the _tag field must be present in the input and must match the expected literal value. The decoded result is a real instance of the error class, complete with .stack, instanceof checks, and yieldability.

Extending Error Classes

Both ErrorClass and TaggedErrorClass support inheritance through the .extend() method. This allows you to create error hierarchies where a base error carries common fields and derived errors add specialized ones.

The .extend() method takes a new identifier and returns a function that accepts the additional fields:

1
import { Schema } from "effect";
2

3
// Base error with common fields
4
class AppError extends Schema.ErrorClass<AppError>("AppError")({
5
  message: Schema.String,
6
  timestamp: Schema.Number,
7
}) {}
8

9
// Extended error with additional fields
10
class DatabaseError extends AppError.extend<DatabaseError>("DatabaseError")({
11
  query: Schema.String,
12
  table: Schema.String,
13
}) {}
14

15
const err = new DatabaseError({
16
  message: "Insert failed",
17
  timestamp: Date.now(),
18
  query: "INSERT INTO orders ...",
19
  table: "orders",
20
});
21

22
console.log(err instanceof AppError); // true
23
console.log(err instanceof DatabaseError); // true
24
console.log(err.message); // "Insert failed"
25
console.log(err.table); // "orders"

The extended class inherits all fields from the parent and adds its own. Instances of the extended class pass instanceof checks for both the parent and the child.

When you extend a TaggedErrorClass, the child class inherits the parent’s _tag value. The _tag is set by the root TaggedErrorClass, not overridden by .extend():

1
import { Schema } from "effect";
2

3
class BaseError extends Schema.TaggedErrorClass<BaseError>()("BaseError", {
4
  message: Schema.String,
5
}) {}
6

7
class DetailedError extends BaseError.extend<DetailedError>("DetailedError")({
8
  details: Schema.String,
9
}) {}
10

11
const err = new DetailedError({
12
  message: "Something failed",
13
  details: "Connection refused on port 5432",
14
});
15

16
// _tag comes from the root TaggedErrorClass
17
console.log(err._tag); // "BaseError"

Because of this behavior, if you need each error to have its own distinct _tag for use with Effect.catchTag, define them as separate TaggedErrorClass declarations rather than using .extend().

Adding Custom Methods and Computed Properties

Since the schema class is a regular JavaScript class, you can add custom methods and properties to it:

1
import { Schema } from "effect";
2

3
class PaymentError extends Schema.TaggedErrorClass<PaymentError>()(
4
  "PaymentError",
5
  {
6
    amount: Schema.Number,
7
    currency: Schema.String,
8
    reason: Schema.String,
9
  },
10
) {
11
  get displayAmount(): string {
12
    return `${this.currency} ${this.amount.toFixed(2)}`;
13
  }
14

15
  get isRetryable(): boolean {
16
    return this.reason === "timeout" || this.reason === "rate_limit";
17
  }
18
}
19

20
const err = new PaymentError({
21
  amount: 49.99,
22
  currency: "USD",
23
  reason: "timeout",
24
});
25

26
console.log(err.displayAmount); // "USD 49.99"
27
console.log(err.isRetryable); // true

Custom methods and getters are regular class members. They have full access to the validated fields and can provide derived values that make error handling more convenient.

Using Schema-Backed Errors with `Effect.catchTag`

The primary reason to use TaggedErrorClass is seamless integration with Effect’s tag-based error handling. Here is a more complete example showing how multiple tagged errors flow through an Effect pipeline:

1
import { Effect, Schema } from "effect";
2

3
// --- Error Definitions ---
4
class NetworkError extends Schema.TaggedErrorClass<NetworkError>()(
5
  "NetworkError",
6
  {
7
    url: Schema.String,
8
    statusCode: Schema.Number,
9
  },
10
) {}
11

12
class ParseError extends Schema.TaggedErrorClass<ParseError>()("ParseError", {
13
  rawBody: Schema.String,
14
  reason: Schema.String,
15
}) {}
16

17
class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()(
18
  "NotFoundError",
19
  {
20
    resource: Schema.String,
21
    id: Schema.String,
22
  },
23
) {}
24

25
// --- Business Logic ---
26
function fetchUser(id: string) {
27
  return Effect.gen(function* () {
28
    // Simulate a network call that might fail
29
    if (id === "bad-network") {
30
      yield* new NetworkError({
31
        url: `/api/users/${id}`,
32
        statusCode: 503,
33
      });
34
    }
35

36
    if (id === "bad-json") {
37
      yield* new ParseError({
38
        rawBody: "{invalid json",
39
        reason: "Unexpected token at position 1",
40
      });
41
    }
42

43
    if (id === "unknown") {
44
      yield* new NotFoundError({
45
        resource: "User",
46
        id,
47
      });
48
    }
49

50
    return { name: "Rob" };
51
  });
52
}
53

54
// --- Error Handling ---
55
const program = fetchUser("unknown").pipe(
56
  Effect.catchTag("NotFoundError", (err) =>
57
    Effect.succeed({ name: `Guest (${err.resource} ${err.id} not found)` }),
58
  ),
59
  Effect.catchTag("NetworkError", (err) =>
60
    Effect.fail(
61
      new Error(`Network failure: ${err.statusCode} from ${err.url}`),
62
    ),
63
  ),
64
  Effect.catchTag("ParseError", (err) =>
65
    Effect.fail(new Error(`Could not parse response: ${err.reason}`)),
66
  ),
67
);
68

69
Effect.runPromise(program).then(console.log);

Output:

1
{ name: 'Guest (User unknown not found)' }

Each Effect.catchTag handler receives the specific error type, fully typed. Inside the "NotFoundError" handler, TypeScript knows that err has .resource and .id. Inside the "NetworkError" handler, it knows about .url and .statusCode. This is all powered by the _tag discriminator that TaggedErrorClass provides automatically.

Schema.ErrorClass

Schema.TaggedErrorClass

Default Value for Error Fields

Zero-Field Tagged Errors

Custom Identifier

ErrorClass vs TaggedErrorClass

Key Features

Yieldable Errors

Serializable

Extending Error Classes

Adding Custom Methods and Computed Properties

Using Schema-Backed Errors with Effect.catchTag

Stay in the loop

Using Schema-Backed Errors with `Effect.catchTag`