Zod safeParse

Quick answer: what does Zod safeParse do?

`safeParse` validates the same schema as `parse`, but it returns a result object instead of throwing on validation failure. Use it when invalid input is expected and your code should branch into success or error handling. The official result shape is a discriminated union: success includes parsed data, failure includes a ZodError.

Basic safeParse example

Call `schema.safeParse(input)` on unknown data, then check `result.success` before reading either `result.data` or `result.error`.

import { z } from "zod";

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
});

const result = UserSchema.safeParse(payload);

if (!result.success) {
  return { ok: false, issues: result.error.issues };
}

return { ok: true, user: result.data };

safeParse return type in TypeScript

The safeParse return type is a discriminated union. Once your code checks `result.success`, TypeScript knows which branch contains parsed data and which branch contains a ZodError.

const result = UserSchema.safeParse(payload);

if (result.success) {
  result.data.email.toLowerCase();
} else {
  result.error.flatten().fieldErrors;
}

Handle safeParse errors

Use `error.flatten()` when forms or API clients need a stable field map. Use `error.issues` when logs, nested paths, or issue codes matter.

const result = CreateUserSchema.safeParse(body);

if (!result.success) {
  return Response.json(
    { error: "Invalid request body", fieldErrors: result.error.flatten().fieldErrors },
    { status: 400 },
  );
}

safeParse vs parse

Use `safeParse` for request bodies, forms, route handlers, server actions, and UI states where invalid data is a normal branch. Use `parse` when invalid data should throw and be handled by a central error layer.

• `safeParse` returns success or error data.
• `parse` returns typed data or throws a ZodError.
• Both methods run the same schema validation rules.

safeParseAsync

Use `safeParseAsync` when the schema has asynchronous refinements or transforms. It keeps the same result shape as safeParse, but returns a promise.

const InviteSchema = z.object({
  email: z.string().email(),
}).refine(async (value) => {
  return await canInviteEmail(value.email);
}, "Email cannot receive invites");

const result = await InviteSchema.safeParseAsync(payload);

Where safeParse fits after generating schemas

A generated Zod schema still needs a failure strategy. After using JSON to Zod or TypeScript to Zod, place `safeParse` at the boundary that receives unknown input and keep parsed data inside the success branch.

API and form safeParse examples

Use the same branching pattern in route handlers, server actions, forms, and fetch wrappers. The important rule is that unknown data should become typed data only after the success branch.

const result = SignupSchema.safeParse(formValues);

if (!result.success) {
  return {
    ok: false,
    fieldErrors: result.error.flatten().fieldErrors,
  };
}

await createAccount(result.data);

Zod safeParse result states

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

Zod validation resources

FAQ

Related tools