zod-validation-error

Welcome to the official documentation for zod-validation-error. This library provides a seamless way to wrap Zod validation errors in user-friendly, highly readable messages.

Overview

Zod is an exceptional TypeScript-first schema declaration and validation library. However, out of the box, Zod's default error outputs are strictly designed for developer consumption. When a validation fails, Zod throws a ZodError containing a deeply nested array of issues. While great for programmatic parsing, exposing this raw JSON to end-users or returning it directly in API responses results in a poor user experience.

zod-validation-error acts as a bridge between Zod's internal error representation and human-readable text. It intercepts complex error arrays and flattens them into concise, readable string messages, all while preserving the original error details for your logs and debugging tools.

The Problem: Raw Zod Errors

When a Zod schema fails validation, it produces a payload similar to this:

[
  {
    "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\""
  }
]

The Solution: zod-validation-error

By passing the error through this library, you immediately get a clean, frontend-ready string:

Validation error: Number must be greater than 0 at "id"; Invalid email at "email"

Key Features

  • Human-Readable Outputs: Converts complex validation issue arrays into single-line, readable strings.
  • Extensive Configuration: Customize separators, prefixes, path inclusions, and localization via robust option objects.
  • Context Preservation: The generated ValidationError class extends the native JavaScript Error and preserves the original Zod issues under error.details.
  • Native Zod Error Map: Ship with a custom createErrorMap that plugs directly into Zod's global configuration to improve errors at the source.
  • Broad Compatibility: Provides dedicated support and exports for both Zod v3 and Zod v4.

When to Use This Library

  • API Responses: You are building REST or GraphQL APIs and want to return clean 400 Bad Request messages to consumers instead of raw JSON dumps.
  • Form Validation: You are handling forms (e.g., React Hook Form) and need to display aggregated error summaries at the top of the form.
  • CLI Tools: You are building a command-line interface that validates user config files and needs to print actionable feedback to the console.

When NOT to Use This Library

  • Internal Application Logging: If you are purely logging errors to an APM tool (like Datadog or Sentry) where structured JSON is preferred for querying, you might want to log the raw ZodError instead, though logging the ValidationError works well too since it retains the .details array.

Next Steps

Ready to get started? Head over to the Installation guide and the Quick Start tutorial to integrate zod-validation-error into your project.