Wrap zod validation errors in user-friendly readable messages.
- User-friendly readable error messages with extensive configuration options;
- Preserves original error details accessible via
error.details
; - Provides a custom error map for automatic message formatting;
- Supports both Zod v3 and v4.
Note: This is the v4 version of zod-validation-error
. If you are looking for the zod v3 support, please click here
npm install zod-validation-error
- Node.js v.18+
- TypeScript v.4.5+
import { z as zod } from 'zod/v4';
import { fromError, createErrorMap } from 'zod-validation-error/v4';
// use custom error map to automatically format messages
// this is optional, but recommended
// without this, zod's native error messages will be used
zod.config({
customError: createErrorMap({
includePath: true,
}),
});
// create zod schema
const zodSchema = zod.object({
id: zod.int().positive(),
email: zod.email(),
});
// parse some invalid value
try {
zodSchema.parse({
id: 1,
email: 'coyote@acme', // note: invalid email
});
} catch (err) {
const validationError = fromError(err);
// the error is now readable by the user
// you may print it to console
console.log(validationError.toString());
// or return it as an actual error
return validationError;
}
Per-format error customization
For more fine-grained control over the error messages, you may pass the error map as an option to the fromError
function.
import { z as zod } from 'zod/v4';
import { fromError, createErrorMap } from 'zod-validation-error/v4';
// create zod schema
const zodSchema = zod.object({
id: zod.int().positive(),
email: zod.email(),
});
// parse some invalid value
try {
zodSchema.parse({
id: 1,
email: 'coyote@acme', // note: invalid email
});
} catch (err) {
// create custom error map
// this is optional, but recommended
// without this, zod's native error messages will be used
// and the error will not be user-friendly
const errorMap = createErrorMap({
includePath: false,
});
const validationError = fromError(err, {
error: errorMap,
});
// the error is now readable by the user
// you may print it to console
console.log(validationError.toString());
// or return it as an actual error
return validationError;
}
Zod errors are difficult to consume for the end-user. This library wraps Zod validation errors in user-friendly readable messages that can be exposed to the outer world, while maintaining the original errors in an array for dev use.
[
{
"origin": "number",
"code": "too_small",
"minimum": 0,
"inclusive": false,
"path": ["id"],
"message": "Number must be greater than 0 at \"id\""
},
{
"origin": "string",
"code": "invalid_format",
"format": "email",
"pattern": "/^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$/",
"path": ["email"],
"message": "Invalid email at \"email\""
}
]
Validation error: Number must be greater than 0 at "id"; Invalid email at "email"
- ValidationError(message[, options])
- createErrorMap(options)
- createMessageBuilder(options)
- isValidationError(error)
- isValidationErrorLike(error)
- isZodErrorLike(error)
- fromError(error[, options])
- fromZodIssue(zodIssue[, options])
- fromZodError(zodError[, options])
- toValidationError([options]) => (error) => ValidationError
Main ValidationError
class, extending native JavaScript Error
.
-
message
- string; error message (required) -
options
- ErrorOptions; error options as per JavaScript definition (optional)-
options.cause
- any; can be used to hold the original zod error (optional)
-
import { ValidationError } from 'zod-validation-error/v4';
const error = new ValidationError('foobar');
console.log(error instanceof Error); // prints true
import { z as zod } from 'zod/v4';
import { ValidationError } from 'zod-validation-error/v4';
const error = new ValidationError('foobar', {
cause: new zod.ZodError([
{
origin: 'number',
code: 'too_small',
minimum: 0,
inclusive: false,
path: ['id'],
message: 'Number must be greater than 0 at "id"',
input: -1,
},
]),
});
console.log(error.details); // prints issues from zod error
Creates zod-validation-error's errorMap
, which is used to format issues into user-friendly error messages.
Meant to be passed as an option to fromError, fromZodIssue, fromZodError, toValidationError or MessageBuilder.
Note: zod-validation-error's errorMap
is an errorMap like all others and thus can also be used directly with zod
(see https://zod.dev/error-customization for further details).
-
options
- Object; formatting options (optional)Name Type Description includePath
boolean
Indicates whether to include the erroneous property key in the error message (optional, defaults to true
)displayInvalidFormatDetails
boolean
Indicates whether to display invalid format details (e.g. regexp pattern) in the error message (optional, defaults to false
)maxAllowedValuesToDisplay
number
Max number of allowed values to display (optional, defaults to 10) allowedValuesSeparator
string
Used to concatenate allowed values in the message (optional, defaults to ", "
)allowedValuesLastSeparator
string | undefined
Used to concatenate last allowed value in the message (optional, defaults to " or "
). Set toundefined
to disable last separator.wrapAllowedValuesInQuote
boolean
Indicates whether to wrap allowed values in quotes (optional, defaults to true
). Note that this only applies to string values.maxUnrecognizedKeysToDisplay
number
Max number of unrecognized keys to display in the error message (optional, defaults to 5
)unrecognizedKeysSeparator
string
Used to concatenate unrecognized keys in the message (optional, defaults to ", "
)unrecognizedKeysLastSeparator
string | undefined
Used to concatenate the last unrecognized key in message (optional, defaults to " and "
). Set toundefined
to disable last separator.wrapUnrecognizedKeysInQuote
boolean
Indicates whether to wrap unrecognized keys in quotes (optional, defaults to true
). Note that this only applies to string keys.issuesInTitleCase
boolean
Indicates whether to convert issues to title case (optional, defaults to true
).unionSeparator
string
Used to concatenate union-issues in user-friendly message (optional, defaults to " or "
)issueSeparator
string
Used to concatenate issues in user-friendly message (optional, defaults to ";"
)dateLocalization
boolean | Intl.LocalesArgument
Indicates whether to localize date values in the error message (optional, defaults to true
). If set totrue
, it will use the default locale of the environment. You can also pass anIntl.LocalesArgument
to specify a custom locale.numberLocalization
boolean | Intl.LocalesArgument
Indicates whether to localize number values in the error message (optional, defaults to true
). If set totrue
, it will use the default locale of the environment. You can also pass anIntl.LocalesArgument
to specify a custom locale.
import { createErrorMap } from 'zod-validation-error/v4';
const messageBuilder = createErrorMap({
includePath: false,
maxAllowedValuesToDisplay: 3,
});
Creates zod-validation-error's default MessageBuilder
, which is used to produce user-friendly error messages.
Meant to be passed as an option to fromError, fromZodIssue, fromZodError or toValidationError.
-
options
- Object; formatting options (optional)Name Type Description maxIssuesInMessage
number
Max issues to include in user-friendly message (optional, defaults to 99
)issueSeparator
string
Used to concatenate issues in user-friendly message (optional, defaults to ";"
)prefix
string | undefined
Prefix to use in user-friendly message (optional, defaults to "Validation error"
). Passundefined
to disable prefix completely.prefixSeparator
string
Used to concatenate prefix with rest of the user-friendly message (optional, defaults to ": "
). Not used whenprefix
isundefined
.error
ErrorMap
Accepts an errorMap
to format individual issues into user-friendly error messages (optional, defaults toundefined
). Note that this is an optional property and if not provided, the default error map will be used. Also, you don't need to pass zod-validation-error'serrorMap
here; you can use your own custom errorMap if you want.
import { createErrorMap, createMessageBuilder } from 'zod-validation-error/v4';
const messageBuilder = createMessageBuilder({
maxIssuesInMessage: 3,
error: createErrorMap({
includePath: false,
}),
});
A type guard utility function, based on instanceof
comparison.
-
error
- error instance (required)
import { z as zod } from 'zod/v4';
import { ValidationError, isValidationError } from 'zod-validation-error/v4';
const err = new ValidationError('foobar');
isValidationError(err); // returns true
const invalidErr = new Error('foobar');
isValidationError(err); // returns false
A type guard utility function, based on heuristics comparison.
Why do we need heuristics since we can use a simple instanceof
comparison? Because of multi-version inconsistencies. For instance, it's possible that a dependency is using an older zod-validation-error
version internally. In such case, the instanceof
comparison will yield invalid results because module deduplication does not apply at npm/yarn level and the prototype is different.
tl;dr if you are uncertain then it is preferable to use isValidationErrorLike
instead of isValidationError
.
-
error
- error instance (required)
import {
ValidationError,
isValidationErrorLike,
} from 'zod-validation-error/v4';
const err = new ValidationError('foobar');
isValidationErrorLike(err); // returns true
const invalidErr = new Error('foobar');
isValidationErrorLike(err); // returns false
A type guard utility function, based on heuristics comparison.
Why do we need heuristics since we can use a simple instanceof
comparison? Because of multi-version inconsistencies. For instance, it's possible that a dependency is using an older zod
version internally. In such case, the instanceof
comparison will yield invalid results because module deduplication does not apply at npm/yarn level and the prototype is different.
-
error
- error instance (required)
import { z as zod } from 'zod/v4';
import { ValidationError, isZodErrorLike } from 'zod-validation-error/v4';
const zodValidationErr = new ValidationError('foobar');
isZodErrorLike(zodValidationErr); // returns false
const genericErr = new Error('foobar');
isZodErrorLike(genericErr); // returns false
const zodErr = new zod.ZodError([
{
origin: 'number',
code: 'too_small',
minimum: 0,
inclusive: false,
path: ['id'],
message: 'Number must be greater than 0 at "id"',
input: -1,
},
]);
isZodErrorLike(zodErr); // returns true
Converts an error to ValidationError
.
What is the difference between fromError
and fromZodError
? The fromError
function is a less strict version of fromZodError
. It can accept an unknown error and attempt to convert it to a ValidationError
.
-
error
- unknown; an error (required) -
options
- Object; formatting options (optional)-
messageBuilder
- MessageBuilder; a function that accepts an array ofzod.ZodIssue
objects and returns a user-friendly error message in the form of astring
(optional).
-
Alternatively, you may pass createMessageBuilder options directly as options
. These will be used as arguments to create the MessageBuilder
instance internally.
Converts a single zod issue to ValidationError
.
-
zodIssue
- zod.ZodIssue; a ZodIssue instance (required) -
options
- Object; formatting options (optional)-
messageBuilder
- MessageBuilder; a function that accepts an array ofzod.ZodIssue
objects and returns a user-friendly error message in the form of astring
(optional).
-
Alternatively, you may pass createMessageBuilder options directly as options
. These will be used as arguments to create the MessageBuilder
instance internally.
Converts zod error to ValidationError
.
Why is the difference between ZodError
and ZodIssue
? A ZodError
is a collection of 1 or more ZodIssue
instances. It's what you get when you call zodSchema.parse()
.
-
zodError
- zod.ZodError; a ZodError instance (required) -
options
- Object; formatting options (optional)-
messageBuilder
- MessageBuilder; a function that accepts an array ofzod.ZodIssue
objects and returns a user-friendly error message in the form of astring
(optional).
-
Alternatively, you may pass createMessageBuilder options directly as options
. These will be used as arguments to create the MessageBuilder
instance internally.
A curried version of fromZodError
meant to be used for FP (Functional Programming). Note it first takes the options object if needed and returns a function that converts the zodError
to a ValidationError
object
toValidationError(options) => (zodError) => ValidationError
import * as Either from 'fp-ts/Either';
import { z as zod } from 'zod/v4';
import { toValidationError, ValidationError } from 'zod-validation-error/v4';
// create zod schema
const zodSchema = zod
.object({
id: zod.int().positive(),
email: zod.email(),
})
.brand<'User'>();
export type User = zod.infer<typeof zodSchema>;
export function parse(
value: zod.input<typeof zodSchema>
): Either.Either<ValidationError, User> {
return Either.tryCatch(() => schema.parse(value), toValidationError());
}
What is the difference between zod-validation-error and zod's own prettifyError?
While both libraries aim to provide a human-readable string representation of a zod error, they differ in several ways...
- End-user focus: zod-validation-error provides opinionated, user-friendly error messages designed to be displayed directly to end-users in forms or API responses, whereas Zod's native error handling seem more developer-focused.
- Customization options: zod-validation-error offers extensive configuration for message formatting, such as controlling path inclusion, allowed values display, localization, and more.
- Error handling: zod-validation-error maintains the original error details while providing a clean, consistent interface through the ValidationError class.
- Integration flexibility: Beyond just formatting, zod-validation-error provides utility functions for error detection and conversion that work well in various architectural patterns, e.g. functional programming.
Disclaimer: as per this comment, we have no intention to antagonize zod. In fact, we are happy to decommission this module assuming it's in the best interest of the community. As of now, it seems that there's room for both zod-validation-error
and prettifyError
, also based on Colin McDonnell's response.
Use the isValidationErrorLike
type guard.
Scenario: Distinguish between ValidationError
VS generic Error
in order to respond with 400 VS 500 HTTP status code respectively.
import { isValidationErrorLike } from 'zod-validation-error/v4';
try {
func(); // throws Error - or - ValidationError
} catch (err) {
if (isValidationErrorLike(err)) {
return 400; // Bad Data (this is a client error)
}
return 500; // Server Error
}
It's possible to implement custom validation logic outside zod
and throw a ValidationError
.
import { ValidationError } from 'zod-validation-error/v4';
import { Buffer } from 'node:buffer';
function parseBuffer(buf: unknown): Buffer {
if (!Buffer.isBuffer(buf)) {
throw new ValidationError('Invalid argument; expected buffer');
}
return buf;
}
import { ValidationError } from 'zod-validation-error/v4';
try {
// do something that throws an error
} catch (err) {
throw new ValidationError('Something went deeply wrong', { cause: err });
}
Zod supports customizing error messages by providing a custom "error map". You may combine this with zod-validation-error
to produce user-friendly messages.
If all you need is to produce user-friendly error messages you may use the errorMap
property.
import { z as zod } from 'zod/v4';
import { fromError, createErrorMap } from 'zod-validation-error/v4';
zod.config({
customError: createErrorMap({
includePath: true,
}),
});
Yes, zod-validation-error
supports CommonJS out-of-the-box. All you need to do is import it using require
.
const { ValidationError } = require('zod-validation-error/v4');
Source code contributions are most welcome. Please open a PR, ensure the linter is satisfied and all tests pass.
Causaly is building the world's largest biomedical knowledge platform, using technologies such as TypeScript, React and Node.js. Find out more about our openings at https://jobs.ashbyhq.com/causaly.
MIT