Understanding Decode Errors

In the previous chapter, we looked at six decoding APIs and saw what happens when decoding fails. But I didn’t explain the error outputs in detail. I will do so in this chapter, so that before we move on to the upcoming chapters, you have a clear mental model of how Effect Schema structures its errors.

There are two error types that decoding APIs produce: a plain JavaScript Error and a SchemaError. Which one you get depends on which API you use.

The reason for the split is that SchemaError is an Effect-native error type. It’s designed to work with Effect’s typed error channel, which is why only the Effect-aware APIs (decodeUnknownExit and decodeUnknownEffect) produce it. The rest operate outside of Effect’s error system, so they use plain JavaScript Error or raw issue objects instead.

Let’s look at each one.

Plain Error

decodeUnknownSync and decodeSync throw a plain JavaScript Error when decoding fails. The human-readable message lives on error.message, and the structured issue data is attached to error.cause.

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

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

8
const decode = Schema.decodeUnknownSync(UserSchema);
9

10
try {
11
  decode({ name: 42, age: 30 });
12
} catch (error) {
13
  if (error instanceof Error) {
14
    console.log("Message:", error.message);
15

16
    if (SchemaIssue.isIssue(error.cause)) {
17
      console.log("Issue:", error.cause);
18
    }
19
  }
20
}

Output:

1
Message: Expected string, got 42
2
  at ["name"]
3
Issue: Composite {
4
  '~effect/SchemaIssue/Issue': '~effect/SchemaIssue/Issue',
5
  _tag: 'Composite',
6
  ast: Objects {
7
    '~effect/Schema': '~effect/Schema',
8
    annotations: undefined,
9
    checks: undefined,
10
    encoding: undefined,
11
    context: undefined,
12
    _tag: 'Objects',
13
    propertySignatures: [ [PropertySignature], [PropertySignature] ],
14
    indexSignatures: []
15
  },
16
  actual: { _id: 'Option', _tag: 'Some', value: { name: 42, age: 30 } },
17
  issues: [
18
    Pointer {
19
      '~effect/SchemaIssue/Issue': '~effect/SchemaIssue/Issue',
20
      _tag: 'Pointer',
21
      path: [Array],
22
      issue: [InvalidType]
23
    }
24
  ]
25
}

error.message gives you a formatted string you can log or display. error.cause holds the raw issue tree, which is the structured representation of what went wrong. We’ll look at the issue tree in detail shortly.

Notice the SchemaIssue.isIssue check. SchemaIssue is a module in the Effect library that contains all the types, constructors, and utilities related to schema issues. You’ll see it throughout this course whenever we work with error data. Here, we use SchemaIssue.isIssue to confirm that error.cause is actually a schema issue before working with it.

SchemaError

decodeUnknownExit and decodeUnknownEffect produce a SchemaError instead of a plain Error. A SchemaError has two properties:

• message: A human-readable string describing the error.
• issue: The raw issue tree.

Let’s see this with decodeUnknownExit:

1
import { Schema } from "effect";
2

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

8
const result = Schema.decodeUnknownExit(UserSchema)({ name: 42, age: 30 });
9
console.log(String(result));

Output:

1
Failure(Cause([Fail(SchemaError(Expected string, got 42
2
  at ["name"]))]))

You’ve seen this output format in the previous chapter. Now let’s break down what each layer means:

• Failure: Decoding did not succeed. The Exit is a Failure variant, not a Success.
• Cause: A container that tracks why the operation failed. Cause is an Effect data structure for representing error chains.
• [...]: The array of Effect-level failure reasons (Fail, Die, Interrupt). For a single schema decode call, this is usually one Fail(SchemaError).
• Fail: A specific type of reason representing a “known” or “expected” failure (as opposed to an unexpected defect).
• SchemaError: The actual error object produced by the Schema module. It contains the formatted message: Expected string, got 42 at ["name"].

To access the SchemaError programmatically, you iterate over result.cause.reasons. If a reason is a Fail variant, its .error property holds the SchemaError:

1
import { Schema } from "effect";
2

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

8
const result = Schema.decodeUnknownExit(User)({ name: 42, age: 30 });
9

10
if (result._tag === "Failure") {
11
  const fail = result.cause.reasons[0];
12
  if (fail._tag === "Fail") {
13
    const schemaError = fail.error;
14
    console.log("Message:", schemaError.message);
15

16
    console.log("Issue:", schemaError.issue);
17
  }
18
}

Output:

1
Message: Expected string, got 42
2
  at ["name"]
3
Issue: Composite {
4
  '~effect/SchemaIssue/Issue': '~effect/SchemaIssue/Issue',
5
  _tag: 'Composite',
6
  ast: Objects {
7
    '~effect/Schema': '~effect/Schema',
8
    annotations: undefined,
9
    checks: undefined,
10
    encoding: undefined,
11
    context: undefined,
12
    _tag: 'Objects',
13
    propertySignatures: [ [PropertySignature], [PropertySignature] ],
14
    indexSignatures: []
15
  },
16
  actual: { _id: 'Option', _tag: 'Some', value: { name: 42, age: 30 } },
17
  issues: [
18
    Pointer {
19
      '~effect/SchemaIssue/Issue': '~effect/SchemaIssue/Issue',
20
      _tag: 'Pointer',
21
      path: [Array],
22
      issue: [InvalidType]
23
    }
24
  ]
25
}

schemaError.message gives you the same human-readable string you saw in the String() output. schemaError.issue gives you the raw issue tree. Let’s look at what that tree contains.

The Issue Tree

The issue property is the source of truth for the error. It’s a tree structure that mirrors the shape of your schema, so you can always trace an error back to the exact part of the input that caused it.

Let’s log the issue tree:

1
import { Schema } from "effect";
2

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

8
const result = Schema.decodeUnknownExit(User)(
9
  { name: 42, age: "old" },
10
  { errors: "all" },
11
);
12

13
if (result._tag === "Failure") {
14
  const fail = result.cause.reasons[0];
15
  if (fail._tag === "Fail") {
16
    console.log(fail.error.issue);
17
  }
18
}

Output:

1
Composite {
2
  '~effect/SchemaIssue/Issue': '~effect/SchemaIssue/Issue',
3
  _tag: 'Composite',
4
  ast: Objects {
5
    '~effect/Schema': '~effect/Schema',
6
    annotations: undefined,
7
    checks: undefined,
8
    encoding: undefined,
9
    context: undefined,
10
    _tag: 'Objects',
11
    propertySignatures: [ [PropertySignature], [PropertySignature] ],
12
    indexSignatures: []
13
  },
14
  actual: { _id: 'Option', _tag: 'Some', value: { name: 42, age: 'old' } },
15
  issues: [
16
    Pointer {
17
      '~effect/SchemaIssue/Issue': '~effect/SchemaIssue/Issue',
18
      _tag: 'Pointer',
19
      path: [Array],
20
      issue: [InvalidType]
21
    },
22
    Pointer {
23
      '~effect/SchemaIssue/Issue': '~effect/SchemaIssue/Issue',
24
      _tag: 'Pointer',
25
      path: [Array],
26
      issue: [InvalidType]
27
    }
28
  ]
29
}

There’s a lot here, but the structure is straightforward once you know what to look for. The tree is made up of three categories of nodes. Let’s walk through them top-down, following the output.

Composite is the root node. It groups multiple child issues together. You can see it has an issues array containing two entries. This is because our input has two fields that failed (name and age), and we used { errors: "all" } to collect all of them. The actual field shows the input that was received: { name: 42, age: 'old' }.

Pointer nodes add location information. Each Pointer wraps a child issue and attaches a path to it, telling you which property the error occurred at. In the output above, there are two Pointer nodes inside the issues array, one for each failing field. When you see a path like ["name"] in an error message, it was built by reading the path from these Pointer nodes.

InvalidType is a leaf node. Leaf nodes are the terminal nodes at the bottom of the tree. They describe what actually went wrong. In this case, both fields have an InvalidType issue, meaning the values had the wrong JavaScript type (expected a string, got a number, and expected a number, got a string).

InvalidType is the most common leaf issue type. Effect Schema has six leaf issue types in total:

• InvalidType: The value has the wrong JavaScript type.
• InvalidValue: The value has the right type but fails a validation rule.
• MissingKey: A required key is absent from the input object.
• UnexpectedKey: An extra key is present in the input object when decoding is configured with { onExcessProperty: "error" }.
• Forbidden: The operation is not allowed (e.g., encoding a value that is decode-only).
• OneOf: A union in oneOf mode matched more than one branch (an ambiguous match).

So putting it all together: a Composite holds multiple issues, each Pointer tells you where the error is, and the leaf node tells you what went wrong. Understanding this structure is important because every error handling feature in Effect Schema ultimately reads from this tree.