Zod safeParse Error Messages in TypeScript

Quick answer: how should safeParse errors be handled?

Use `safeParse` when validation failure is expected and the caller needs a structured response. The result is a discriminated union: success includes parsed data, failure includes a `ZodError` with issues that can be flattened, logged, or mapped into API field messages.

Basic safeParse result

The common pattern is to branch on `result.success`. Once TypeScript sees the success check, it narrows `result.data` and `result.error` correctly. If the schema started in the JSON to Zod converter, keep this handling near the boundary that receives unknown data.

const result = UserSchema.safeParse(payload);

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

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

Turn issues into field errors

Use `flatten()` when a form or API client wants errors grouped by field. This is easier to consume than sending the full issues array to every caller.

const result = CreateUserSchema.safeParse(body);

if (!result.success) {
  const fieldErrors = result.error.flatten().fieldErrors;

  return Response.json(
    { error: "Invalid request body", fieldErrors },
    { status: 400 },
  );
}

Preserve path information

Use `error.issues` when nested paths matter. Each issue includes a path, code, and message, which is useful for API logs, table rows, nested form fields, and support debugging.

• Use `issue.path.join(".")` for readable nested field names.
• Keep `issue.code` in logs so repeated failures can be grouped.
• Return concise user-facing messages and keep raw payloads out of public responses.

API response pattern

For route handlers and server actions, safeParse makes validation a normal control-flow branch instead of an exception. Return a 400 response for invalid input and only call business logic with parsed data.

export async function POST(request: Request) {
  const body: unknown = await request.json();
  const parsed = CreateProjectSchema.safeParse(body);

  if (!parsed.success) {
    return Response.json(
      { error: "Validation failed", issues: parsed.error.flatten().fieldErrors },
      { status: 400 },
    );
  }

  return Response.json(await createProject(parsed.data));
}

UI message pattern

Client-side UI usually wants short messages by field. Keep the raw Zod error in developer logs or telemetry and render only the first message for each input when the form is compact.

• Use field errors for input-level messages.
• Use form errors for cross-field or object-level failures.
• Use `safeParseAsync` when refinements or transforms are asynchronous.

Production checklist

Before shipping safeParse error handling, make sure callers get stable error shapes and tests cover invalid, missing, null, and nested values.

• Do not expose secret raw payloads in validation responses.
• Test `flatten()` output for the fields your UI or API client expects.
• Log enough issue metadata to debug contract drift.
• Keep parse for unexpected invalid upstream data and safeParse for recoverable validation branches.

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

Zod validation resources

FAQ

Related comparisons

Related tools