NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #1538 most downloaded on npm
Wrap zod validation errors in user-friendly readable messages
Last release 11 months ago
03 Nov 2025
Release timing varies
gaps range from 9 days to 8 months
Nearly every release is documented
notes for 36 of 37 stable releases
3 versions withdrawn
withdrawn after publishing
4 years old
42 releases · first in 2022
One column per quarter.
2c5a3c4 : Change error messages to consistently follow the expected <expectation>, received <realization> format (breaking change).
Note: This is a major release due to the change in the error messages. Otherwise, it is 100% compatible with the previous version. If you don't really care about the exact wording of the error messages, you can safely upgrade to v.5.0.0 without any code changes.
expected <expectation>, received <realization> format (breaking change).reportInput option.6fd928f : Improve handling for zod.discriminatedUnion errors.
f8b7c44 : Handle no path property in "invalid_union" by @MiaInturi
9be31d2 : Make v4 the default export of zod-validation-error
Nothing published for this version
Nothing published for this version
6640d99 : Add zod@3.24.4 compatibility, which was inadvertently broken by adopting the zod/v3 import paths.
zod/v3 import paths.Nothing published for this version
3809f85 : Include paths of sub-issues of union.
e7713d5 : Add compatibility with older node versions and module-resolution strategies + improve docs
bf72012 : Add support for zod v4
94d5f3b: Bump zod to v.3.24.4 in package.json as dev + peer dependency
3a7928c: Customize error messages using a MessageBuilder.
42bc4fe: Test Version Packages fix
66f5b5d: Match ZodError via heuristics instead of relying on instanceof.
66f5b5d: Match ZodError via heuristics instead of relying on instanceof.
Why? Because we want to ensure that zod-validation-error works smoothly even when multiple versions of zod have been installed in the same project.
6b4e8a0: Introduce fromError API which is a less strict version of fromZodError
fromError API which is a less strict version of fromZodErrorfromZodError and throw dev-friendly TypeError suggesting usage of fromError instead3f5e391: Better error messages for zod.function() types
2f1ef27: Bundle code as a single index.js (cjs) or index.mjs (esm) file. Restore exports configuration in package.json.
24b773c: Revert package.json exports causing dependant projects to fail
3382fbc: 1. Fix issue with ErrorOptions not being found in earlier to es2022 typescript configs. 2. Add exports definition to package.json to help bun
deb4639: BREAKING CHANGE: Refactor ValidationError to accept ErrorOptions as second parameter.
deb4639: BREAKING CHANGE: Refactor ValidationError to accept ErrorOptions as second parameter.
What changed?
Previously, ValidationError accepted Array<ZodIssue> as 2nd parameter. Now, it accepts ErrorOptions which contains a cause property. If cause is a ZodError then it will extract the attached issues and expose them over error.details.
Why?
This change allows us to use ValidationError like a native JavaScript Error. For example, we can now do:
import { ValidationError } from 'zod-validation-error';
try {
// attempt to do something that might throw an error
} catch (err) {
throw new ValidationError('Something went deeply wrong', { cause: err });
}
How can you update your code?
If you are using ValidationError directly, then you need to update your code to pass ErrorOptions as a 2nd parameter.
import { ValidationError } from 'zod-validation-error';
// before
const err = new ValidationError('Something went wrong', zodError.issues);
// after
const err = new ValidationError('Something went wrong', { cause: zodError });
If you were never using ValidationError directly, then you don't need to do anything.
b084ad5: Add includePath option to allow users take control on whether to include the erroneous property name in their error messages.
includePath option to allow users take control on whether to include the erroneous property name in their error messages.b199ca1: Update toValidationError() to return only ValidationError instances
b199ca1: Update toValidationError() to return only ValidationError instances
This change only affects users of toValidationError(). The method was previously returning Error | ValidationError and now returns only ValidationError.
82b7739: Expose errorMap property to use with zod.setErrorMap() method
8893d16: Expose fromZodIssue method
218da5f: fix: casing typo of how zod namespace was referenced
8ccae09: Added exports of types for parameters of fromZodError function
449477d: Switch to using npm instead of yarn. Update node requirement to v.16+
f3aa0b2: Better handling for single-item paths
f3aa0b2: Better handling for single-item paths
Given a validation error at array position 1 the error output would read Error X at "[1]". After this change, the error output reads Error X at index 1.
Likewise, previously a validation error at property "_" would yield Error X at "["_"]". Now it yieldsError X at "\*" which reads much better.
b693f52: Handle unicode and special-character identifiers
b868741: Fix broken links in API docs
90b2f83: Update ZodValidationError to behave more like a native Error constructor. Make options argument optional. Add name property and define toStri
a2e5322: Ensure union errors do not output duplicate messages
9c4c4ec: Make union errors more detailed
59ad8df: Expose isValidationErrorLike type-guard
fa81c9b: Drop SWC; Fix ESM export
Nothing published for this version
Nothing published for this version
7f420d1: Update build and npm badges on README.md
fde2f50: update dependency in package json so the user does not have to manually install it, will be installed on package install.
67336ac: Enable automatic release to npm
### Minor Changes - fcda684: Initial functionality
Your coding agent can read these notes before it upgrades. Set up the MCP server →