Skip to content

NarixHine/uni-chem / .agents/skills/safe-action-validation-errors

safe-action-validation-errors

Verified

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

FileKindSize
SKILL.mdskill md3.2 KB
custom-errors.mdmarkdown2.9 KB
error-shapes.mdmarkdown4.2 KB

error-shapes.md

View on GitHub
# Validation Error Shapes

> **Note:** Action files require a `"use server"` directive — omitted from examples below for brevity.

## Formatted (Default)

Nested structure mirroring the schema, with `_errors` arrays at each level:

```ts
// Schema: z.object({ email: z.string().email(), name: z.string().min(2) })
// Formatted errors:
{
  _errors: [],                    // root-level errors
  email: { _errors: ["Invalid email"] },
  name: { _errors: ["Too short"] },
}
```

Access: `result.validationErrors?.email?._errors?.[0]`

## Flattened

Flat structure with `formErrors` (root) and `fieldErrors` (one level deep):

```ts
// Same schema, flattened errors:
{
  formErrors: [],                       // root-level errors
  fieldErrors: {
    email: ["Invalid email"],
    name: ["Too short"],
  },
}
```

Access: `result.validationErrors?.fieldErrors?.email?.[0]`

**Note:** Flattened mode only processes one level deep. Nested object field errors are not included.

## Setting the Default Shape

### Client-Level Default

```ts
import { createSafeActionClient } from "next-safe-action";

export const actionClient = createSafeActionClient({
  defaultValidationErrorsShape: "flattened", // "formatted" | "flattened"
});
```

All actions created from this client will use the flattened shape by default.

### Per-Action Override

Override the shape for a specific action using `handleValidationErrorsShape` in `.inputSchema()`:

```ts
import { flattenValidationErrors, formatValidationErrors } from "next-safe-action";

// Client uses "formatted" by default, but this action uses "flattened"
export const myAction = actionClient
  .inputSchema(
    z.object({ email: z.string().email() }),
    {
      handleValidationErrorsShape: async (ve) => flattenValidationErrors(ve),
    }
  )
  .action(async ({ parsedInput }) => {
    // ...
  });
```

### Custom Shape

Return any shape you want from `handleValidationErrorsShape`:

```ts
export const myAction = actionClient
  .inputSchema(
    z.object({ email: z.string().email(), name: z.string() }),
    {
      handleValidationErrorsShape: async (ve) => {
        // Custom: just a flat record of field → first error
        const errors: Record<string, string> = {};
        for (const [key, value] of Object.entries(ve)) {
          if (key !== "_errors" && value?._errors?.[0]) {
            errors[key] = value._errors[0];
          }
        }
        return errors;
      },
    }
  )
  .action(async ({ parsedInput }) => { /* ... */ });

// result.validationErrors: { email?: string; name?: string }
```

## Utility Functions

### formatValidationErrors(ve)

Identity function — returns errors as-is (formatted shape). Useful when you want to be explicit:

```ts
import { formatValidationErrors } from "next-safe-action";

handleValidationErrorsShape: async (ve) => formatValidationErrors(ve),
```

### flattenValidationErrors(ve)

Converts formatted → flattened shape:

```ts
import { flattenValidationErrors } from "next-safe-action";

handleValidationErrorsShape: async (ve) => flattenValidationErrors(ve),
```

## handleValidationErrorsShape Receives Context

The function receives a second `utils` argument with full context:

```ts
handleValidationErrorsShape: async (ve, { clientInput, bindArgsClientInputs, metadata, ctx }) => {
  // Log the validation failure with context
  logger.warn("Validation failed", {
    action: metadata.actionName,
    userId: ctx.userId,
    errors: ve,
  });
  return flattenValidationErrors(ve);
},
```

## throwValidationErrors

When enabled, validation errors throw `ActionValidationError` instead of being returned in `result.validationErrors`. The thrown error contains the **shaped** validation errors (after `handleValidationErrorsShape` runs).

```ts
// Enable globally
const actionClient = createSafeActionClient({
  throwValidationErrors: true,
});

// Or per-action
export const myAction = actionClient
  .inputSchema(schema)
  .action(serverCodeFn, {
    throwValidationErrors: true,
  });

// With custom error message
export const myAction = actionClient
  .inputSchema(schema)
  .action(serverCodeFn, {
    throwValidationErrors: {
      overrideErrorMessage: async (validationErrors) =>
        `Validation failed: ${JSON.stringify(validationErrors)}`,
    },
  });
```
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall