zod-error-map

Type-safe, customizable error message mapping for Zod validation.

Installation

npm install zod-error-map

Usage

Basic Usage (Zod v4)

setZodErrorMap() resolves your project's zod peer dependency automatically, so you don't need to pass it in:

import { z } from 'zod'
import { setZodErrorMap } from 'zod-error-map'

setZodErrorMap()

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
})

schema.parse({ email: 'invalid', password: '123' })
// Error: The 'email' must be a valid email address

You can still pass the Zod instance explicitly (useful when working with multiple Zod installations):

import { z } from 'zod'
import { setZodErrorMap } from 'zod-error-map'

setZodErrorMap(z)

Custom Configuration

import { setZodErrorMap, ErrorCode } from 'zod-error-map'

setZodErrorMap({
  defaultError: 'Validation failed',
  formatMessages: {
    email: (label) => `Please enter a valid email for ${label.quoted}`,
  },
  builders: {
    [ErrorCode.TOO_SMALL]: (issue, label) =>
      `${label.bare} needs at least ${issue.minimum} characters`,
  },
})

Using the Error Mapper Directly

import { createErrorMapper } from 'zod-error-map'

const mapper = createErrorMapper({
  defaultError: 'Invalid input',
})

const message = mapper.format({
  code: 'invalid_type',
  path: ['email'],
  input: undefined,
  expected: 'string',
})
// "The email is required"

Zod v3 Compatibility

setZodErrorMap() detects Zod v3 automatically and calls z.setErrorMap() under the hood:

import { setZodErrorMap } from 'zod-error-map'

setZodErrorMap()

You can also wire the error map manually:

import { z } from 'zod'
import { createZodErrorMap } from 'zod-error-map'

z.setErrorMap(createZodErrorMap())

API

setZodErrorMap(config?)

Sets the global Zod error map, resolving the peer zod dependency automatically. Uses z.config() on Zod v4 or z.setErrorMap() on Zod v3.

setZodErrorMap(z, config?)

Same as above, but with an explicit Zod instance/namespace instead of resolving the peer dependency.

createZodErrorMap(config?)

Creates a Zod error map compatible with z.setErrorMap() (Zod v3).

createErrorMapper(config?)

Creates an error mapper instance with custom configuration.

Configuration Options

| Option | Type | Description | |--------|------|-------------| | defaultError | string | Default error message when no builder matches | | builders | Record<string, MessageBuilder> | Custom message builders by error code | | formatMessages | Record<string, (label) => string> | Custom messages for format validation errors |

Error Codes

• ErrorCode.INVALID_TYPE - Type mismatch or missing required field
• ErrorCode.TOO_SMALL - Value below minimum length/value
• ErrorCode.TOO_BIG - Value above maximum length/value
• ErrorCode.INVALID_FORMAT - Invalid format (email, uuid, url, etc.)
• ErrorCode.CUSTOM - Custom validation errors

Format Types

FormatType.EMAIL, FormatType.UUID, FormatType.URL, FormatType.REGEX, FormatType.CUID, FormatType.CUID2, FormatType.ULID, FormatType.IP, FormatType.DATE, FormatType.DATETIME, FormatType.TIME

License

MIT