Zod v3 Support

zod-validation-error is fully backwards compatible with Zod v3. However, between versions 3 and 4, Zod made significant architectural changes to its internal types, error mapping signatures, and global configuration mechanics.

To ensure flawless type-safety and runtime stability for both versions, zod-validation-error heavily compartmentalizes its exports.

If your project uses Zod v3, you must use the /v3 submodule imports.

1. Updating Imports

Any time you import from zod-validation-error, simply append /v3 to the import path. This ensures you are pulling the logic and types specifically compiled against the Zod v3 API.

// ❌ INCORRECT (Defaults to Zod v4)
import { fromError } from 'zod-validation-error';

// ✅ CORRECT (Zod v3 specific)
import { fromError } from 'zod-validation-error/v3';

2. Global Error Map Configuration

In Zod v4, error maps are configured via a global zod.config() object, and you generate them using createErrorMap().

In Zod v3, error maps are applied using zod.setErrorMap(). Furthermore, the v3 implementation of zod-validation-error exports a pre-built constant named errorMap rather than a factory function.

Zod v3 Error Map Setup

import { z as zod } from 'zod/v3';
import { errorMap } from 'zod-validation-error/v3';

// Apply the error map globally for Zod v3
zod.setErrorMap(errorMap);

3. Message Builder Options Differences

In the v3 implementation, the options interface passed to fromError, fromZodError, and createMessageBuilder is slightly different.

It relies on CreateMessageBuilderProps. It shares most foundational properties with v4 (such as issueSeparator, prefix, and includePath), but it does not support advanced formatting flags like forceTitleCase or deeply customized localization options, because those rely on the v4-specific parsing architecture.

Zod v3 Message Builder Setup

import { createMessageBuilder } from 'zod-validation-error/v3';

const messageBuilder = createMessageBuilder({
  includePath: false,
  maxIssuesInMessage: 3,
});

Migration Path

If you upgrade your project from Zod v3 to Zod v4 in the future:

  1. Remove the /v3 suffix from all zod-validation-error imports.
  2. Replace zod.setErrorMap(errorMap) with zod.config({ customError: createErrorMap() }).
  3. Review any custom MessageBuilder options, as you will have access to more powerful formatting toggles.