`createErrorMap`

createErrorMap allows you to inject zod-validation-error's high-quality string generation directly into Zod's internal validation pipeline.

Signature

function createErrorMap(
  partialOptions?: Partial<ErrorMapOptions>
): zod.$ZodErrorMap

Overview

When a Zod schema fails, Zod internally calls an "Error Map" function to figure out what text to attach to the message property of the ZodIssue. By default, Zod's error map produces technical, developer-centric strings.

If you register our custom Error Map, Zod will inherently produce human-friendly messages immediately at the source. This means even if you don't use fromError, error.issues[0].message will still look great.

Global Setup

import { z as zod } from 'zod';
import { createErrorMap } from 'zod-validation-error';

// Apply globally for all schemas (Zod v4 syntax)
zod.config({
  customError: createErrorMap(),
});

(Note: For Zod v3, you use zod.setErrorMap(errorMap). See Zod v3 Support).

Local Setup

You can also apply the Error Map to a single parse execution:

const result = schema.safeParse(data, {
    error: createErrorMap({ reportInput: 'typeAndValue' })
});

Configuration Options (`ErrorMapOptions`)

The Error Map handles how specific data types, formats, and inputs are rendered. You can deeply customize this behavior.

Option	Type	Default	Description
`displayInvalidFormatDetails`	`boolean`	`false`	If true, displays deep details. E.g., for a Regex failure, it will print `expected string to match pattern "/^[a-z]+$/"` instead of just `pattern`.
`reportInput`	`false \| "type" \| "typeAndValue"`	`"type"`	Controls how the received data is reported. `"type"`: "received number". `"typeAndValue"`: "received number (123)". `false`: Doesn't report what was received.
`maxAllowedValuesToDisplay`	`number`	`10`	For Enums and Literals: Max number of options to print before truncating (e.g., `"a", "b" or 8 more value(s)`).
`allowedValuesSeparator`	`string`	`", "`	String used to join enum/literal options.
`allowedValuesLastSeparator`	`string \| undefined`	`" or "`	String used before the final enum option.
`wrapAllowedValuesInQuote`	`boolean`	`true`	If true, string literals are wrapped in quotes (`"active"` vs `active`).
`maxUnrecognizedKeysToDisplay`	`number`	`5`	For `strict()` objects: Max number of extra keys to list before truncating.
`unrecognizedKeysSeparator`	`string`	`", "`	String used to join unrecognized keys.
`unrecognizedKeysLastSeparator`	`string \| undefined`	`" and "`	String used before the final unrecognized key.
`wrapUnrecognizedKeysInQuote`	`boolean`	`true`	If true, object keys are wrapped in quotes.
`dateLocalization`	`boolean \| Intl.LocalesArgument`	`true`	Controls how Date objects are stringified. If `true`, uses the Node/Browser environment's default locale. Can be set to a specific locale like `'en-US'` or `'ar-EG'`.
`numberLocalization`	`boolean \| Intl.LocalesArgument`	`true`	Controls how numbers are stringified (e.g., adding commas). Supports specific locales.

Examples

Localizing Numbers and Dates

If you want to ensure numbers are formatted specifically for an Arabic (Egypt) locale:

const localizedErrorMap = createErrorMap({
  numberLocalization: 'ar-EG',
  dateLocalization: 'ar-EG'
});

const schema = zod.number().min(1234);
const res = schema.safeParse(5, { error: localizedErrorMap });

// Output will format '1234' into '١٬٢٣٤' according to the locale
// "expected number to be greater than or equal to ١٬٢٣٤"

Detailed Input Reporting

When reportInput is set to typeAndValue, the user sees exactly what they inputted wrong, which is highly effective for CLI tools.

const schema = zod.literal('production');

const res = schema.safeParse('staging', { 
    error: createErrorMap({ reportInput: 'typeAndValue' }) 
});

// Output: "expected value to be \"production\", received \"staging\""

createErrorMap