Use when working with validation errors -- returnValidationErrors, formatted vs flattened shapes, custom validation error shapes, throwValidationErrors, or displaying field-level and form-level errors

next safe action Validation Errors Two Sources of Validation Errors 1. Schema validation — automatic when input doesn't match .inputSchema() 2. 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: returnValidationErrors Throws a ActionServerValidationError that the framework catches and returns as result.validationErrors . It never returns — it always throws. For expected non validation errors ("out of stock", "not found"), the sibling helper returnServerError(payload) works the same way (throws internally, never returns) but sets result.serverError to the typed payload, bypassing handleServerError . See the safe action client skill. Root Level Errors Use errors at the top level for form wide errors: Supporting Docs [Custom validation errors and returnValidationErrors patterns](./custom errors.md) [Formatted vs flattened shapes, per action override](./error shapes.md) Displaying Validation Errors

safe-action-validation-errors