safeParse

Zod · Reference cheat sheet

📋 Overview

safeParse returns a discriminated result instead of throwing. Prefer it at HTTP/form boundaries where invalid input is expected.

API	Behavior
`schema.parse(data)`	Returns value or throws `ZodError`
`schema.safeParse(data)`	`\{ success, data \}` or `\{ success, error \}`
`schema.parseAsync` / `safeParseAsync`	Async refinements/transforms
`error.flatten()`	Field errors for forms
`error.format()`	Nested error tree

Branch on success:

const result = User.safeParse(payload);
if (!result.success) {
  console.error(result.error.flatten());
  return;
}
console.log(result.data.email);

HTTP handler style:

const parsed = Body.safeParse(await req.json());
if (!parsed.success) {
  return Response.json(parsed.error.flatten(), { status: 400 });
}

flatten for UI:

const { fieldErrors, formErrors } = error.flatten();

After success === true, TypeScript narrows data — don't access data on the failure branch.
Swallowing error without logging loses diagnostics.
parse in a hot request path without try/catch can crash the process if unhandled.