ZodError flatten vs format

Quick answer: flatten or format?

Use a flatten shape for flat forms where you want `fieldErrors[name]` message arrays, and a treeify/format shape for nested data where errors must follow deep paths. In Zod 4, prefer the top-level `z.flattenError()` and `z.treeifyError()` helpers; the `error.flatten()` and `error.format()` methods still work but are legacy.

z.flattenError(): field errors for flat objects

Flatten produces a single level of `fieldErrors` keyed by the top-level property name, plus `formErrors` for issues that are not tied to a field. This maps cleanly onto form inputs, which is why it is the default choice for form validation.

import * as z from "zod";

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

const result = SignupSchema.safeParse(input);

if (!result.success) {
  const flat = z.flattenError(result.error);
  // {
  //   formErrors: [],
  //   fieldErrors: {
  //     email: ["Invalid email address"],
  //     password: ["String must contain at least 8 character(s)"]
  //   }
  // }
}

z.treeifyError(): nested errors for deep data

Treeify mirrors the schema structure so errors stay attached to deep paths. Each node exposes an `errors` array, and object or array nodes expose `properties` and `items` branches. Use it when flatten would collapse nested paths you need to render.

const OrderSchema = z.object({
  customer: z.object({
    email: z.string().email(),
  }),
  items: z.array(z.object({ sku: z.string().min(1) })),
});

const result = OrderSchema.safeParse(input);

if (!result.success) {
  const tree = z.treeifyError(result.error);
  // tree.properties?.customer?.properties?.email?.errors -> ["Invalid email address"]
  // tree.properties?.items?.items?.[0]?.properties?.sku?.errors -> ["..."]
}

Legacy error.flatten() and error.format()

The instance methods still exist on ZodError for compatibility. `error.flatten()` returns the same shape as `z.flattenError()`, and `error.format()` returns a nested tree similar to `z.treeifyError()` but using `_errors` arrays. New code should prefer the top-level helpers, which are the maintained path going forward.

// Legacy (still works in Zod 4)
const flat = result.error.flatten();
const nested = result.error.format(); // nodes use _errors: string[]

// Preferred in Zod 4
const flat2 = z.flattenError(result.error);
const nested2 = z.treeifyError(result.error);

Which shape fits forms vs APIs

The right helper depends on how the consumer renders errors. Match the output shape to the UI or API contract so you do not reshape the data twice.

• Forms with flat fields: use `z.flattenError()` and read `fieldErrors[name]`.
• Nested objects or arrays of objects: use `z.treeifyError()` to keep errors on deep paths.
• Human-readable logs or a single message string: use `z.prettifyError(error)`.
• Public API responses: map issues yourself from `error.issues` so you control wording and never leak internal paths.

Migrating Zod 3 error handling to Zod 4

If you are upgrading, the methods you already call keep working, so migration can be incremental. Move to the top-level helpers as you touch each error path, and note that `treeifyError` uses `errors` arrays where `format()` used `_errors`.

• Replace `error.flatten()` with `z.flattenError(error)` (identical shape).
• Replace `error.format()` with `z.treeifyError(error)` and update `_errors` reads to `errors`.
• Generate a starter schema with JSON to Zod, then choose the error helper at the boundary that handles unknown input.

ZodError error helpers in Zod 4

Use FrameworkKit to generate the starter code, then review the output before shipping it in production.

Zod validation resources

FAQ

Related tools