Zod Error Formatting and Performance#

Zod emphasizes completeness and correctness in error reporting. When validation fails, Zod produces a $ZodError (the ZodError class in the zod package is a subclass with additional convenience methods) that contains an .issues array — each issue includes a human-readable message, an error code, a path, and structured metadata about the failure 1.

Error Formatting Utilities#

Zod provides several utilities to transform a ZodError into a more usable shape. See the Formatting errors reference for full examples.

z.treeifyError(error)#

Converts the flat .issues array into a nested object that mirrors the schema 2. Each node has an errors array for messages at that path, plus properties (for objects) and items (for arrays) to traverse deeper. Use optional chaining (?.) when accessing nested nodes.

const tree = z.treeifyError(result.error);
tree.properties?.username?.errors; // errors at username
tree.properties?.favoriteNumbers?.items?.[1]?.errors; // errors at index 1

z.formatError() — present in earlier docs — is now deprecated; use z.treeifyError() instead 2.

z.flattenError(error)#

Designed for flat (one-level-deep) schemas — the most common case. Returns { formErrors: string[], fieldErrors: { [key: string]: string[] } } 2. formErrors holds top-level errors (path []); fieldErrors maps each field key to its error messages. Nested validation failures for deeply-nested schemas are collapsed to their first-level key.

z.prettifyError(error)#

Returns a human-readable string formatted with ✖ bullets and → at <path> annotations 2. Intended for logging and debugging, not for surfacing to end users programmatically.

✖ Unrecognized key: "extraKey"
✖ Invalid input: expected string, received number
  → at username
✖ Invalid input: expected number, received string
  → at favoriteNumbers[1]

Error Customization Quick Reference#

Errors can be customized at multiple levels; the precedence order from highest to lowest is 1:

1. Check-level — z.string().min(5, "Too short!")
2. Schema-level — z.string("Not a string!")
3. Per-parse — schema.parse(data, { error: iss => "..." })
4. Global error map — z.config({ customError: iss => "..." })
5. Locale error map — z.config(z.locales.en())

The error param accepts a string or a function receiving an issue context object (iss) with code, input, path, inst, and schema 1. Return undefined to defer to the next level in the chain.

For internationalization, Zod ships built-in locales (Arabic, French, Japanese, and 70+ others) exported from zod/v4/locales 1. Regular zod loads the en locale automatically; zod/mini loads none by default and uses "Invalid input" as the fallback.

AOT Compilation Performance (z.compile())#

Introduced in Zod 4, z.compile() performs ahead-of-time (AOT) compilation of a schema into a flat, loop-free JavaScript validator via new Function() 3. This fast-path function is used for valid inputs; on failure it falls back to the standard parser to provide full error detail. Results and error messages are identical to the uncompiled schema.

Speedups#

Benchmarks show speedups that scale with schema complexity 3:

On the Moltar benchmark (parseSafe category), Zod 4 compiled reaches 47.5 M ops/sec, compared to 11.6 M for uncompiled Zod 4 and 1.2 M for Zod 3 3. In the assertLoose category Zod 4 compiled reaches 60.6 M ops/sec, competitive with typia (74.9 M) and arktype (66.2 M).

Invalid inputs pay for both the fast path and the fallback, so compilation mostly speeds up the success path. Failures are dominated by the fallback and see minimal benefit 3.

Opt-in Methods#

z.compile(schema) — compiles a single schema; returns a compiled copy. Compile after all chaining (.refine(), .extend(), etc.) since derived schemas are uncompiled 3.

import "zod/compile" — enables global auto-compilation. Every schema constructed after this import is compiled lazily on first parse. Suitable for applications; not recommended for libraries. Can also be set as a Node.js CLI flag: node --import zod/compile app.js 3.

Limitations#

The following features cannot be compiled 3 — z.compile() silently returns the original schema:

• async refinements, transforms, or checks
• z.xor(), recursive schemas, z.coerce.*
• Checks with a custom when condition
• .catch() given a callback (constant .catch(value) compiles fine)

Pass { strict: true } to throw instead of silently falling back — useful to verify hot-path schemas actually compiled (ZodCompileAsyncError or ZodCompileUnsupportedError) 3.

CSP / No-eval Environments#

z.compile() uses new Function(), so it is unavailable in CSP/no-eval environments. Set z.config({ jitless: true }) to disable global auto-compilation; calling z.compile() directly still attempts code generation and returns the schema uncompiled if rejected 3.

Bundle Size Impact#

The compiler adds ~7 KB gzipped (28 KB minified) and is fully tree-shaken when unused 3:

Zod vs. Alternatives (Non-TypeScript Environments)#

Zod works in plain JavaScript as well as TypeScript, and its zero-dependency, 2 KB core bundle 4 makes it competitive with alternatives like Joi even in non-TypeScript environments.

On the Moltar benchmark, Zod 4 compiled outperforms yup (121 k ops/sec), Zod 3 (1.2 M), effect (1.7 M), and valibot (1.8 M) by a large margin 3. Libraries like Joi are not directly benchmarked in Zod's own suite, but the Moltar numbers place Zod 4 compiled near the top of runtime validators.

For backend workloads, bundle size concerns are largely irrelevant: benchmarks show Lambda cold-start time increases only ~0.6 ms for the full 17 KB (gzipped) Zod package 5. The decision to use Zod Mini over Zod mainly applies to front-end bundles targeting users on slow mobile connections 5.

Key References#