skills.rest
NarixHine
NarixHineCOMMUNITY
Explore all skills by this author →
GitHub

safe-action-validation-errors

Handle validation errors in next-safe-action server actions with formatted or flattened shapes.

Updated Jul 8, 2026
Search Tags:#typescript#next.js#zod#server actions#form errors#validation errors#next-safe-action
One-click install
npx skills add https://github.com/NarixHine/uni-chem --skill safe-action-validation-errors-narixhine
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: safe-action-validation-errors
Source: https://github.com/NarixHine/uni-chem/tree/main/.agents/skills/safe-action-validation-errors
Command: npx skills add https://github.com/NarixHine/uni-chem --skill safe-action-validation-errors-narixhine

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires next-safe-action, zod, and includes references (resource) components.

What problem does it solve? When building Next.js server actions with next-safe-action, developers struggle to return, shape, and display validation errors consistently—especially when combining automatic schema validation with manual business-rule checks like "email already taken". ## Core Features & Use Cases - Manual Validation Errors: Use returnValidationErrors to throw field-level, form-level, and nested-object errors from server code after schema validation passes. - Error Shape Control: Switch between formatted (nested _errors) and flattened (formErrors/fieldErrors) shapes globally, per-action, or with fully custom shapes via handleValidationErrorsShape. - Throwing Mode: Enable throwValidationErrors to raise ActionValidationError instead of returning errors in the result object. - Use Case: In a registration form, check whether an email is already registered in the database, return a field-level error, and render it under the email input in the client component. ## Quick Start Ask the AI to add a returnValidationErrors check to your next-safe-action server action and display the resulting field errors in your React form.

Frequently Asked Questions about safe-action-validation-errors

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I return custom validation errors from a next-safe-action server action?▼

Call returnValidationErrors with your Zod schema and an errors object matching the schema shape, such as { email: { _errors: ["This email is already registered"] } }. It throws internally and never returns, so the framework delivers the errors as result.validationErrors on the client.

What is the difference between formatted and flattened validation errors in next-safe-action?▼

Formatted is the default nested shape mirroring the schema with _errors arrays at each level. Flattened produces formErrors and fieldErrors one level deep. Set the default with defaultValidationErrorsShape on the client or override per action with handleValidationErrorsShape.

How do I display field-level validation errors in a React form?▼

Access result.validationErrors with the formatted shape via result.validationErrors?.email?._errors and map each message to a paragraph element. With the flattened shape, use result.validationErrors?.fieldErrors?.email and result.validationErrors?.formErrors for root-level messages.

Can next-safe-action throw validation errors instead of returning them?▼

Yes, enable throwValidationErrors globally on the client or per action so validation failures throw ActionValidationError, which you catch in try/catch. The thrown error contains the shaped validation errors and supports a custom overrideErrorMessage.

What are the limitations of the flattened validation error shape?▼

The flattened shape only processes one level deep, so errors on nested object fields are not included in fieldErrors. For deeply nested schemas, keep the default formatted shape or write a custom handleValidationErrorsShape function.

Related Skills

Explore More Software Engineering Skills→
fusenginefusengine
1

astro-actions

Implements type-safe Astro server actions with Zod validation and progressive form enhancement.

Community
Intermediate
vipulj226-designvipulj226-design

forms

Handle form validation and submission in React with react-hook-form.

Community
Intermediate
Mohamedghaly140Mohamedghaly140

clerk-nextjs-patterns

Implement Clerk authentication patterns for Next.js middleware, server actions, and caching.

Community
Advanced
djankiesdjankies

integrating-zod-frameworks

Integrate Zod v4 schemas with React Hook Form, Next.js Server Actions, Express, and tRPC.

Community
Intermediate