Safe Action Validation Errors

If you're using next-safe-action and need to handle validation errors beyond schema checks, this covers the patterns. It explains returnValidationErrors for business logic failures like "email already taken" and how those errors match the same structure as schema validation errors. The formatted shape mirrors your Zod schema with _errors arrays at each level, while the flattened shape separates fieldErrors and formErrors. Useful for knowing when to throw validation errors in server code versus letting schema validation catch malformed input. The display examples show exactly how to render field-level and form-level errors in either shape.

skills.sh installs: 1.2K
GitHub stars: 1
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add next-safe-action/skills --skill safe-action-validation-errors --agent claude-code

Installs into .claude/skills of the current project.

Files

next-safe-action Validation Errors

Two Sources of Validation Errors

Schema validation — automatic when input doesn't match .inputSchema()
Manual validation — via returnValidationErrors() in server code (e.g., "email already taken")

Both produce the same error structure on the client.

Default Error Shape (Formatted)

Mirrors the schema structure with _errors arrays at each level:

// For schema: z.object({ email: z.string().email(), address: z.object({ city: z.string() }) })
{
  _errors: ["Form-level error"],                    // root errors
  email: { _errors: ["Invalid email address"] },    // field errors
  address: {
    _errors: ["Address section error"],
    city: { _errors: ["City is required"] },        // nested field errors
  },
}