Errors

For error handling I use internally with ValiError my own error class, which supports you in case of an issue, with extensive information.

Issues

When validating unknown data against a schema, I collect information about the existing issues and at the end, if there is at least one issue, I throw a single ValiError that contains all issues. Therefore, each instance of a ValiError always contains at least one Issue.

Overview

You can access the issues of a ValiError via .issues. The issues are an array of objects. In the following I will explain you exactly what information an issue contains and how this information can help you.

type Issue = {
  // Required info
  reason: IssueReason;
  validation: string;
  origin: 'key' | 'value';
  message: string;
  input: any;

  // Optional info
  path?: PathItem[];
  issues?: Issues;
  abortEarly?: boolean;
  abortPipeEarly?: boolean;
  skipPipe?: boolean;
};

Required info

Each issue contains the following required information.

Reason

reason describes the reason of the problem. If an input does not match the data type, for example a number was passed instead of a string, reason has the value 'type'. In all other cases the reason is not the datatype but the actual content of the data. For example, if a string is invalid because it does not match a regex, reason has the value 'string'.

Validation

validation describes which function did the validation. If the schema function array detects that the input is not an array, validation has the value 'array'. If the minLength validation function detects that an array is too short, validation has the value 'min_length'.

Origin

origin describes the source of the issue and, except for an issue on a key of a map or record, always has the value 'value'.

Message

message contains a human-understandable error message that can be fully customized by you, as described here.

Input

input contains the specific data where the issue was found. For complex data, for example objects, input contains the value of the respective key that does not match the schema.

Optional info

Some issue contain further optional information.

Path

path is an array of objects that describes where an issue is located within complex data. Each path item contains the following information.

type PathItem = {
  schema: string;
  input: any;
  key: string | number | symbol;
  value: any;
};

For example, you can use the following code to create a dot path.

const dotPath = issue.path.map((item) => item.key).join('.');

Issues

issues currently only occur when using union or unionAsync and contains all issues of the schemas of an union type.

Abort

abortEarly and abortPipeEarly gives you an info that the validation was aborted prematurely. You can find more info about this in the parse data guide.

Formatting

For common use cases like forms, I help you with small functions to format the issues of an ValiError. However, once you understand how my errors work, you can easily format them yourself and put them in the right form for your use case.

Flatten errors

If you are only interested in the error messages to show them to your users, you can convert a ValiError to a flat object with flatten. Below is an example.

import { flatten, object, parse, string } from 'valibot'; // 0.84 kB

const ObjectSchema = object({
  key: string('Value of "key" is missing.'),
  nested: object({
    key: string('Value of "nested.key" is missing.'),
  }),
});

try {
  parse(ObjectSchema, { nested: {} }); // Throws an error
} catch (error) {
  console.log(flatten(error));
}

The ValiError thrown in the code sample above this text contains the following issues.

[
  {
    reason: 'type',
    validation: 'string',
    origin: 'value',
    message: 'Value of "key" is missing.',
    input: undefined,
    path: [
      {
        schema: 'object',
        input: { nested: {} },
        key: 'key',
        value: undefined,
      },
    ],
  },
  {
    reason: 'type',
    validation: 'string',
    origin: 'value',
    message: 'Value of "nested.key" is missing.',
    input: undefined,
    path: [
      {
        schema: 'object',
        input: { nested: {} },
        key: 'nested',
        value: {},
      },
      {
        schema: 'object',
        input: {},
        key: 'key',
        value: undefined,
      },
    ],
  },
];

However, with the help of flatten the ValiError was converted to the following object.

{
  nested: {
    key: ['Value of "key" is missing.'],
    'nested.key': ['Value of "nested.key" is missing.']
  }
}