Error Messages

Default Error Messages

By default, when a parsing error occurs, the system automatically generates an informative message based on the schema’s structure and the nature of the error (see TreeFormatter for more informations). For example, if a required property is missing or a data type does not match, the error message will clearly state the expectation versus the actual input.

Example (Type Mismatch)

1
import { Schema } from "effect"
2

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

8
Schema.decodeUnknownSync(Person)(null)
9
// Output: ParseError: Expected { readonly name: string; readonly age: number }, actual null

Example (Missing Properties)

1
import { Schema } from "effect"
2

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

8
Schema.decodeUnknownSync(Person)({}, { errors: "all" })
9
/*
10
throws:
11
ParseError: { readonly name: string; readonly age: number }
12
├─ ["name"]
13
│  └─ is missing
14
└─ ["age"]
15
   └─ is missing
16
*/

Example (Incorrect Property Type)

1
import { Schema } from "effect"
2

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

8
Schema.decodeUnknownSync(Person)({ name: null, age: "age" }, { errors: "all" })
9
/*
10
throws:
11
ParseError: { readonly name: string; readonly age: number }
12
├─ ["name"]
13
│  └─ Expected string, actual null
14
└─ ["age"]
15
   └─ Expected number, actual "age"
16
*/

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.annotations({ identifier: "Name" })
4

5
const Age = Schema.Number.annotations({ identifier: "Age" })
6

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

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

18
Schema.decodeUnknownSync(Person)({}, { errors: "all" })
19
/*
20
throws:
21
ParseError: Person
22
├─ ["name"]
23
│  └─ is missing
24
└─ ["age"]
25
   └─ is missing
26
*/
27

28
Schema.decodeUnknownSync(Person)({ name: null, age: null }, { errors: "all" })
29
/*
30
throws:
31
ParseError: Person
32
├─ ["name"]
33
│  └─ Expected Name, actual null
34
└─ ["age"]
35
   └─ Expected Age, actual null
36
*/

When a refinement fails, the default error message indicates whether the failure occurred in the “from” part or within the predicate defining the refinement:

Example (Refinement Errors)

1
import { Schema } from "effect"
2

3
const Name = Schema.NonEmptyString.annotations({ identifier: "Name" })
4

5
const Age = Schema.Positive.pipe(Schema.int({ identifier: "Age" }))
6

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

12
// From side failure
13
Schema.decodeUnknownSync(Person)({ name: null, age: 18 })
14
/*
15
throws:
16
ParseError: Person
17
└─ ["name"]
18
   └─ Name
19
      └─ From side refinement failure
20
         └─ Expected string, actual null
21
*/
22

23
// Predicate refinement failure
24
Schema.decodeUnknownSync(Person)({ name: "", age: 18 })
25
/*
26
throws:
27
ParseError: Person
28
└─ ["name"]
29
   └─ Name
30
      └─ Predicate refinement failure
31
         └─ Expected a non empty string, actual ""
32
*/

In the first example, the error message indicates a “from side” refinement failure in the name property, specifying that a string was expected but received null. In the second example, a “predicate” refinement failure is reported, indicating that a non-empty string was expected for name but an empty string was provided.

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 { ParseResult, Schema } from "effect"
2

3
const schema = Schema.transformOrFail(Schema.String, Schema.String.pipe(Schema.minLength(2)), {
4
  strict: true,
5
  decode: (s, _, ast) =>
6
    s.length > 0 ? ParseResult.succeed(s) : ParseResult.fail(new ParseResult.Type(ast, s)),
7
  encode: ParseResult.succeed,
8
})
9

10
// Encoded side failure
11
Schema.decodeUnknownSync(schema)(null)
12
/*
13
throws:
14
ParseError: (string <-> minLength(2))
15
└─ Encoded side transformation failure
16
   └─ Expected string, actual null
17
*/
18

19
// transformation failure
20
Schema.decodeUnknownSync(schema)("")
21
/*
22
throws:
23
ParseError: (string <-> minLength(2))
24
└─ Transformation process failure
25
   └─ Expected (string <-> minLength(2)), actual ""
26
*/
27

28
// Type side failure
29
Schema.decodeUnknownSync(schema)("a")
30
/*
31
throws:
32
ParseError: (string <-> minLength(2))
33
└─ Type side transformation failure
34
   └─ minLength(2)
35
      └─ Predicate refinement failure
36
         └─ Expected a string at least 2 character(s) long, actual "a"
37
*/

Custom Error Messages

You have the capability to define custom error messages specifically tailored for different parts of your schema using the message annotation. This allows developers to provide more context-specific feedback which can improve the debugging and validation processes.

Here’s an overview of the MessageAnnotation type, which you can use to craft these messages:

type MessageAnnotation = (issue: ParseIssue) =>
  | string
  | Effect<string>
  | {
      readonly message: string | Effect<string>
      readonly override: boolean
    }

Return Type	Description
`string`	Provides a static message that directly describes the error.
`Effect<string>`	Utilizes dynamic messages that can incorporate results from synchronous processes or rely on optional dependencies.
Object (with `message` and `override`)	Allows you to define a specific error message along with a boolean flag (`override`). This flag determines if the custom message should supersede any default or nested custom messages, providing precise control over the error output displayed to users.

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
ParseError: Expected string, actual null
11
*/
12

13
// Define a string schema with a custom error message
14
const MyStringWithMessage = Schema.String.annotations({
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
ParseError: not a string
23
*/

Example (Custom Error Message for a Union Schema with Override Option)

1
import { Schema } from "effect"
2

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

6
// Decode `null`, resulting in default union error messages
7
Schema.decodeUnknownSync(MyUnion)(null)
8
/*
9
throws:
10
ParseError: string | number
11
├─ Expected string, actual null
12
└─ Expected number, actual null
13
*/
14

15
// Define a union schema with a custom message and override flag
16
const MyUnionWithMessage = Schema.Union(Schema.String, Schema.Number).annotations({
17
  message: () => ({
18
    message: "Please provide a string or a number",
19
    // Ensures this message replaces all nested messages
20
    override: true,
21
  }),
22
})
23

24
// Decode with the custom schema, showing the new error message
25
Schema.decodeUnknownSync(MyUnionWithMessage)(null)
26
/*
27
throws:
28
ParseError: Please provide a string or a number
29
*/

General Guidelines for Messages

The general logic followed to determine the messages is as follows:

If no custom messages are set, the default message related to the innermost schema where the operation (i.e., decoding or encoding) failed is used.
If custom messages are set, then the message corresponding to the first failed schema is used, starting from the innermost schema to the outermost. However, if the failing schema does not have a custom message, then the default message is used.
As an opt-in feature, you can override guideline 2 by setting the override flag to true. This allows the custom message to take precedence over all other custom messages from inner schemas. This is to address the scenario where a user wants to define a single cumulative custom message describing the properties that a valid value must have and does not want to see default messages.

Let’s see some practical examples.

Scalar Schemas

Example (Simple Custom Message for Scalar Schema)

1
import { Schema } from "effect"
2

3
const MyString = Schema.String.annotations({
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) // "my custom message"
13
}

This example demonstrates setting a custom message on the last refinement in a chain of refinements. As you can see, the custom message is only used if the refinement related to maxLength fails; otherwise, default messages are used.

Example (Custom Message on Last Refinement in Chain)

1
import { Schema } from "effect"
2

3
const MyString = Schema.String.pipe(Schema.minLength(1), Schema.maxLength(2)).annotations({
4
  // This message is displayed only if the last filter (`maxLength`) fails
5
  message: () => "my custom message",
6
})
7

8
const decode = Schema.decodeUnknownSync(MyString)
9

10
try {
11
  decode(null)
12
} catch (e: any) {
13
  console.log(e.message)
14
  /*
15
   minLength(1) & maxLength(2)
16
   └─ From side refinement failure
17
      └─ minLength(1)
18
         └─ From side refinement failure
19
            └─ Expected string, actual null
20
  */
21
}
22

23
try {
24
  decode("")
25
} catch (e: any) {
26
  console.log(e.message)
27
  /*
28
   minLength(1) & maxLength(2)
29
   └─ From side refinement failure
30
      └─ minLength(1)
31
         └─ Predicate refinement failure
32
            └─ Expected a string at least 1 character(s) long, actual ""
33
  */
34
}
35

36
try {
37
  decode("abc")
38
} catch (e: any) {
39
  console.log(e.message)
40
  // "my custom message"
41
}

When setting multiple custom messages, the one corresponding to the first failed predicate is used, starting from the innermost refinement to the outermost:

Example (Custom Messages for Multiple Refinements)

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
  .annotations({ message: () => "String custom message" })
6
  .pipe(
7
    // This message is displayed only if the filter `minLength` fails
8
    Schema.minLength(1, { message: () => "minLength custom message" }),
9
    // This message is displayed only if the filter `maxLength` fails
10
    Schema.maxLength(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) // String custom message
19
}
20

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

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

You have the option to change the default behavior by setting the override flag to true. This is useful when you want to create a single comprehensive custom message that describes the required properties of a valid value without displaying default messages.

Example (Overriding Default Messages)

1
import { Schema } from "effect"
2

3
const MyString = Schema.String.pipe(Schema.minLength(1), Schema.maxLength(2)).annotations({
4
  // By setting the `override` flag to `true`, this message will always be shown for any error
5
  message: () => ({ message: "my custom message", override: true }),
6
})
7

8
const decode = Schema.decodeUnknownSync(MyString)
9

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

16
try {
17
  decode("")
18
} catch (e: any) {
19
  console.log(e.message) // my custom message
20
}
21

22
try {
23
  decode("abc")
24
} catch (e: any) {
25
  console.log(e.message) // my custom message
26
}

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 { ParseResult, Schema } from "effect"
2

3
const IntFromString = Schema.transformOrFail(
4
  // This message is displayed only if the input is not a string
5
  Schema.String.annotations({ message: () => "please enter a string" }),
6
  // This message is displayed only if the input can be converted
7
  // to a number but it's not an integer
8
  Schema.Int.annotations({ message: () => "please enter an integer" }),
9
  {
10
    strict: true,
11
    decode: (s, _, ast) => {
12
      const n = Number(s)
13
      return Number.isNaN(n)
14
        ? ParseResult.fail(new ParseResult.Type(ast, s))
15
        : ParseResult.succeed(n)
16
    },
17
    encode: (n) => ParseResult.succeed(String(n)),
18
  },
19
)
20
  // This message is displayed only if the input
21
  // cannot be converted to a number
22
  .annotations({ message: () => "please enter a parseable string" })
23

24
const decode = Schema.decodeUnknownSync(IntFromString)
25

26
try {
27
  decode(null)
28
} catch (e: any) {
29
  console.log(e.message) // please enter a string
30
}
31

32
try {
33
  decode("1.2")
34
} catch (e: any) {
35
  console.log(e.message) // please enter an integer
36
}
37

38
try {
39
  decode("not a number")
40
} catch (e: any) {
41
  console.log(e.message) // please enter a parseable string
42
}

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, pipe } from "effect"
2

3
const schema = Schema.Struct({
4
  outcomes: pipe(
5
    Schema.Array(
6
      Schema.Struct({
7
        id: Schema.String,
8
        text: pipe(
9
          Schema.String.annotations({
10
            message: () => "error_invalid_outcome_type",
11
          }),
12
          Schema.minLength(1, { message: () => "error_required_field" }),
13
          Schema.maxLength(50, {
14
            message: () => "error_max_length_field",
15
          }),
16
        ),
17
      }),
18
    ),
19
    Schema.minItems(1, { message: () => "error_min_length_field" }),
20
  ),
21
})
22

23
Schema.decodeUnknownSync(schema, { errors: "all" })({
24
  outcomes: [],
25
})
26
/*
27
throws
28
ParseError: { readonly outcomes: minItems(1) }
29
└─ ["outcomes"]
30
   └─ error_min_length_field
31
*/
32

33
Schema.decodeUnknownSync(schema, { errors: "all" })({
34
  outcomes: [
35
    { id: "1", text: "" },
36
    { id: "2", text: "this one is valid" },
37
    { id: "3", text: "1234567890".repeat(6) },
38
  ],
39
})
40
/*
41
throws
42
ParseError: { readonly outcomes: minItems(1) }
43
└─ ["outcomes"]
44
   └─ minItems(1)
45
      └─ From side refinement failure
46
         └─ ReadonlyArray<{ readonly id: string; readonly text: minLength(1) & maxLength(50) }>
47
            ├─ [0]
48
            │  └─ { readonly id: string; readonly text: minLength(1) & maxLength(50) }
49
            │     └─ ["text"]
50
            │        └─ error_required_field
51
            └─ [2]
52
               └─ { readonly id: string; readonly text: minLength(1) & maxLength(50) }
53
                  └─ ["text"]
54
                     └─ error_max_length_field
55
*/

Effectful messages

Error messages can go beyond simple strings by returning an Effect, allowing them to access dependencies, such as an internationalization service. This approach lets messages dynamically adjust based on external context or services. Below is an example illustrating how to create effect-based messages.

Example (Effect-Based Message with Internationalization Service)

1
import { Context, Effect, Either, Option, Schema, ParseResult } from "effect"
2

3
// Define an internationalization service for custom messages
4
class Messages extends Context.Tag("Messages")<
5
  Messages,
6
  {
7
    NonEmpty: string
8
  }
9
>() {}
10

11
// Define a schema with an effect-based message
12
// that depends on the Messages service
13
const Name = Schema.NonEmptyString.annotations({
14
  message: () =>
15
    Effect.gen(function* () {
16
      // Attempt to retrieve the Messages service
17
      const service = yield* Effect.serviceOption(Messages)
18
      // Use a fallback message if the service is not available
19
      return Option.match(service, {
20
        onNone: () => "Invalid string",
21
        onSome: (messages) => messages.NonEmpty,
22
      })
23
    }),
24
})
25

26
// Attempt to decode an empty string without providing the Messages service
27
Schema.decodeUnknownEither(Name)("").pipe(
28
  Either.mapLeft((error) =>
29
    ParseResult.TreeFormatter.formatError(error).pipe(Effect.runSync, console.log),
30
  ),
31
)
32
// Output: Invalid string
33

34
// Provide the Messages service to customize the error message
35
Schema.decodeUnknownEither(Name)("").pipe(
36
  Either.mapLeft((error) =>
37
    ParseResult.TreeFormatter.formatError(error).pipe(
38
      Effect.provideService(Messages, {
39
        NonEmpty: "should be non empty",
40
      }),
41
      Effect.runSync,
42
      console.log,
43
    ),
44
  ),
45
)
46
// Output: should be non empty

Missing messages

You can provide custom messages for missing fields or tuple elements using the missingMessage 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.propertySignature(Schema.String).annotations({
5
    // Custom message if "name" is missing
6
    missingMessage: () => "Name is required",
7
  }),
8
})
9

10
Schema.decodeUnknownSync(Person)({})
11
/*
12
throws:
13
ParseError: { readonly name: string }
14
└─ ["name"]
15
   └─ Name is required
16
*/

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.element(Schema.Number).annotations({
5
    // Message if X is missing
6
    missingMessage: () => "X coordinate is required",
7
  }),
8
  Schema.element(Schema.Number).annotations({
9
    // Message if Y is missing
10
    missingMessage: () => "Y coordinate is required",
11
  }),
12
)
13

14
Schema.decodeUnknownSync(Point)([], { errors: "all" })
15
/*
16
throws:
17
ParseError: readonly [number, number]
18
├─ [0]
19
│  └─ X coordinate is required
20
└─ [1]
21
   └─ Y coordinate is required
22
*/