Error Messages

Default Error Messages

By default, a SchemaError formats its issue with a concise message and a path when the failure is nested (see Error Formatters). For example, if a required property is missing or a value has the wrong type, the message states what was expected and where the failure occurred.

Example (Type Mismatch)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.Finite,
6
})
7

8
Schema.decodeUnknownSync(Person)(null)
9
// throws: SchemaError: Expected object

Example (Missing Properties)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.Finite,
6
})
7

8
Schema.decodeUnknownSync(Person)({}, { errors: "all" })
9
/*
10
throws:
11
SchemaError: Missing key
12
  at ["name"]
13
Missing key
14
  at ["age"]
15
*/

Example (Incorrect Property Type)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.Finite,
6
})
7

8
Schema.decodeUnknownSync(Person)({ name: null, age: "age" }, { errors: "all" })
9
/*
10
throws:
11
SchemaError: Expected string
12
  at ["name"]
13
Expected number
14
  at ["age"]
15
*/

Enhancing Clarity in Error Messages with Identifiers

In scenarios where a schema has multiple fields or nested structures, the default error messages can become overly complex and verbose. To address this, you can enhance the clarity and brevity of these messages by utilizing annotations such as identifier, title, and description.

Example (Using Identifiers for Clarity)

1
import { Schema } from "effect"
2

3
const Name = Schema.String.annotate({ identifier: "Name" })
4

5
const Age = Schema.Finite.annotate({ identifier: "Age" })
6

7
const Person = Schema.Struct({
8
  name: Name,
9
  age: Age,
10
}).annotate({ identifier: "Person" })
11

12
Schema.decodeUnknownSync(Person)(null)
13
/*
14
throws:
15
SchemaError: Expected Person
16
*/
17

18
Schema.decodeUnknownSync(Person)({}, { errors: "all" })
19
/*
20
throws:
21
SchemaError: Missing key
22
  at ["name"]
23
Missing key
24
  at ["age"]
25
*/
26

27
Schema.decodeUnknownSync(Person)({ name: null, age: null }, { errors: "all" })
28
/*
29
throws:
30
SchemaError: Expected Name
31
  at ["name"]
32
Expected Age
33
  at ["age"]
34
*/

Checks

A check runs only after the base schema accepts the input. Base-type failures and check failures therefore have distinct messages.

Example (Base-Type and Check Errors)

1
import { Schema } from "effect"
2

3
const Name = Schema.String.check(
4
  Schema.isNonEmpty({ expected: "a non-empty name" }),
5
)
6

7
const Person = Schema.Struct({
8
  name: Name,
9
}).annotate({ identifier: "Person" })
10

11
// The base string schema rejects null before the check runs
12
Schema.decodeUnknownSync(Person)({ name: null })
13
/*
14
throws:
15
SchemaError: Expected string
16
  at ["name"]
17
*/
18

19
// The input is a string, so the non-empty check runs and fails
20
Schema.decodeUnknownSync(Person)({ name: "" })
21
/*
22
throws:
23
SchemaError: Expected a non-empty name
24
  at ["name"]
25
*/

Transformations

Transformations between different types or formats can occasionally result in errors. The system provides a structured error message to specify where the error occurred:

Encoded Side Failure: Errors on this side typically indicate that the input to the transformation does not match the expected initial type or format. For example, receiving a null when a string is expected.
Transformation Process Failure: This type of error arises when the transformation logic itself fails, such as when the input does not meet the criteria specified within the transformation functions.
Type Side Failure: Occurs when the output of a transformation does not meet the schema requirements on the decoded side. This can happen if the transformed value fails subsequent validations or conditions.

Example (Transformation Errors)

1
import { Effect, Schema, SchemaGetter, SchemaIssue } from "effect"
2

3
const schema = Schema.String.pipe(
4
  Schema.decodeTo(Schema.String.check(Schema.isMinLength(2)), {
5
    decode: SchemaGetter.transformOrFail((s) =>
6
      s.length > 0
7
        ? Effect.succeed(s)
8
        : Effect.fail(new SchemaIssue.InvalidValue()),
9
    ),
10
    encode: SchemaGetter.passthrough(),
11
  }),
12
)
13

14
// Encoded side failure
15
Schema.decodeUnknownSync(schema)(null)
16
/*
17
throws:
18
SchemaError: Expected string
19
*/
20

21
// transformation failure
22
Schema.decodeUnknownSync(schema)("")
23
/*
24
throws:
25
SchemaError: Expected a valid value
26
*/
27

28
// Type side failure
29
Schema.decodeUnknownSync(schema)("a")
30
/*
31
throws:
32
SchemaError: Expected a value with a length of at least 2
33
*/

Custom Error Messages

Use the message annotation to replace the default message for a schema node or check.

type MessageAnnotation = string

Example (Adding a Custom Error Message to a String Schema)

1
import { Schema } from "effect"
2

3
// Define a string schema without a custom message
4
const MyString = Schema.String
5

6
// Attempt to decode `null`, resulting in a default error message
7
Schema.decodeUnknownSync(MyString)(null)
8
/*
9
throws:
10
SchemaError: Expected string
11
*/
12

13
// Define a string schema with a custom error message
14
const MyStringWithMessage = Schema.String.annotate({
15
  message: "not a string",
16
})
17

18
// Decode with the custom schema, showing the new error message
19
Schema.decodeUnknownSync(MyStringWithMessage)(null)
20
/*
21
throws:
22
SchemaError: not a string
23
*/

Example (Custom Error Message for a Union Schema)

1
import { Schema } from "effect"
2

3
// Define a union schema without a custom message
4
const MyUnion = Schema.Union([Schema.String, Schema.Finite])
5

6
// Decode `null`, resulting in default union error messages
7
Schema.decodeUnknownSync(MyUnion)(null)
8
/*
9
throws:
10
SchemaError: Expected string | number
11
*/
12

13
// Define a union schema with a custom message
14
const MyUnionWithMessage = Schema.Union([
15
  Schema.String,
16
  Schema.Finite,
17
]).annotate({
18
  message: "Please provide a string or a number",
19
})
20

21
// Decode with the custom schema, showing the new error message
22
Schema.decodeUnknownSync(MyUnionWithMessage)(null)
23
/*
24
throws:
25
SchemaError: Please provide a string or a number
26
*/

General Guidelines for Messages

Attach message to the node whose failure you want to replace. For a specific check, pass the annotation to that check constructor; annotating a schema after .check(...) targets its last check. If a different inner node fails, its own message or default formatting is used.

Scalar Schemas

Example (Simple Custom Message for Scalar Schema)

1
import { Schema } from "effect"
2

3
const MyString = Schema.String.annotate({
4
  message: "my custom message",
5
})
6

7
const decode = Schema.decodeUnknownSync(MyString)
8

9
try {
10
  decode(null)
11
} catch (e: any) {
12
  console.log(e.message)
13
  e.message // => "my custom message"
14
}

Checks

This example sets a custom message on the last check in a chain. The custom message is used only when isMaxLength fails; otherwise, default messages are used.

Example (Custom Message on the Last Check)

1
import { Schema } from "effect"
2

3
const MyString = Schema.String.check(
4
  Schema.isMinLength(1),
5
  Schema.isMaxLength(2),
6
).annotate({
7
  // This message is displayed only if the last filter (`isMaxLength`) fails
8
  message: "my custom message",
9
})
10

11
const decode = Schema.decodeUnknownSync(MyString)
12

13
try {
14
  decode(null)
15
} catch (e: any) {
16
  console.log(e.message)
17
  e.message // => "Expected string"
18
}
19

20
try {
21
  decode("")
22
} catch (e: any) {
23
  console.log(e.message)
24
  e.message // => "Expected a value with a length of at least 1"
25
}
26

27
try {
28
  decode("abc")
29
} catch (e: any) {
30
  console.log(e.message)
31
  e.message // => "my custom message"
32
}

When several checks have custom messages, the first failing check supplies the message:

Example (Custom Messages for Multiple Checks)

1
import { Schema } from "effect"
2

3
const MyString = Schema.String
4
  // This message is displayed only if a non-String is passed as input
5
  .annotate({ message: "String custom message" })
6
  .check(
7
    // This message is displayed only if the filter `isMinLength` fails
8
    Schema.isMinLength(1, { message: "minLength custom message" }),
9
    // This message is displayed only if the filter `isMaxLength` fails
10
    Schema.isMaxLength(2, { message: "maxLength custom message" }),
11
  )
12

13
const decode = Schema.decodeUnknownSync(MyString)
14

15
try {
16
  decode(null)
17
} catch (e: any) {
18
  console.log(e.message)
19
  e.message // => "String custom message"
20
}
21

22
try {
23
  decode("")
24
} catch (e: any) {
25
  console.log(e.message)
26
  e.message // => "minLength custom message"
27
}
28

29
try {
30
  decode("abc")
31
} catch (e: any) {
32
  console.log(e.message)
33
  e.message // => "maxLength custom message"
34
}

Transformations

In this example, IntFromString is a transformation schema that converts strings to integers. It applies specific validation messages based on different scenarios.

Example (Custom Error Messages for String-to-Integer Transformation)

1
import { Effect, Schema, SchemaGetter, SchemaIssue } from "effect"
2

3
const IntFromString = Schema.String
4
  // This message is displayed only if the input is not a string
5
  .annotate({ message: "please enter a string" })
6
  .pipe(
7
    Schema.decodeTo(
8
      // This message is displayed only if the input can be converted
9
      // to a number but it's not an integer
10
      Schema.Int.annotate({ message: "please enter an integer" }),
11
      {
12
        decode: SchemaGetter.transformOrFail((s) => {
13
          const n = Number(s)
14
          return Number.isNaN(n)
15
            ? Effect.fail(
16
                // This message is displayed only if the input
17
                // cannot be converted to a number
18
                new SchemaIssue.InvalidValue({
19
                  message: "please enter a parseable string",
20
                }),
21
              )
22
            : Effect.succeed(n)
23
        }),
24
        encode: SchemaGetter.transform((n) => String(n)),
25
      },
26
    ),
27
  )
28

29
const decode = Schema.decodeUnknownSync(IntFromString)
30

31
try {
32
  decode(null)
33
} catch (e: any) {
34
  console.log(e.message)
35
  e.message // => "please enter a string"
36
}
37

38
try {
39
  decode("1.2")
40
} catch (e: any) {
41
  console.log(e.message)
42
  e.message // => "please enter an integer"
43
}
44

45
try {
46
  decode("not a number")
47
} catch (e: any) {
48
  console.log(e.message)
49
  e.message // => "please enter a parseable string"
50
}

Compound Schemas

The custom message system becomes especially handy when dealing with complex schemas, unlike simple scalar values like string or number. For instance, consider a schema comprising nested structures, such as a struct containing an array of other structs. Let’s explore an example demonstrating the advantage of default messages in handling decoding errors within such nested structures:

Example (Custom Error Messages in Nested Schemas)

1
import { Schema } from "effect"
2

3
const schema = Schema.Struct({
4
  outcomes: Schema.Array(
5
    Schema.Struct({
6
      id: Schema.String,
7
      text: Schema.String.annotate({
8
        message: "error_invalid_outcome_type",
9
      }).check(
10
        Schema.isMinLength(1, { message: "error_required_field" }),
11
        Schema.isMaxLength(50, {
12
          message: "error_max_length_field",
13
        }),
14
      ),
15
    }),
16
  ).check(Schema.isMinLength(1, { message: "error_min_length_field" })),
17
})
18

19
Schema.decodeUnknownSync(schema, { errors: "all" })({
20
  outcomes: [],
21
})
22
/*
23
throws
24
SchemaError: error_min_length_field
25
  at ["outcomes"]
26
*/
27

28
Schema.decodeUnknownSync(schema, { errors: "all" })({
29
  outcomes: [
30
    { id: "1", text: "" },
31
    { id: "2", text: "this one is valid" },
32
    { id: "3", text: "1234567890".repeat(6) },
33
  ],
34
})
35
/*
36
throws
37
SchemaError: error_required_field
38
  at ["outcomes"][0]["text"]
39
error_max_length_field
40
  at ["outcomes"][2]["text"]
41
*/

Missing messages

You can provide custom messages for missing fields or tuple elements using the messageMissingKey annotation.

Example (Custom Message for Missing Property)

In this example, a custom message is defined for a missing name property in the Person schema.

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String.pipe(
5
    // Custom message if "name" is missing
6
    Schema.annotateKey({ messageMissingKey: "Name is required" }),
7
  ),
8
})
9

10
Schema.decodeUnknownSync(Person)({})
11
/*
12
throws:
13
SchemaError: Name is required
14
  at ["name"]
15
*/

Example (Custom Message for Missing Tuple Elements)

Here, each element in the Point tuple schema has a specific custom message if the element is missing.

1
import { Schema } from "effect"
2

3
const Point = Schema.Tuple([
4
  Schema.Finite.pipe(
5
    // Message if X is missing
6
    Schema.annotateKey({ messageMissingKey: "X coordinate is required" }),
7
  ),
8
  Schema.Finite.pipe(
9
    // Message if Y is missing
10
    Schema.annotateKey({ messageMissingKey: "Y coordinate is required" }),
11
  ),
12
])
13

14
Schema.decodeUnknownSync(Point)([], { errors: "all" })
15
/*
16
throws:
17
SchemaError: X coordinate is required
18
  at [0]
19
Y coordinate is required
20
  at [1]
21
*/