Error handling

next-safe-action has three categories of errors, each handled differently:

Validation errors

Validation errors occur when the client sends data that doesn't match the input schema. They're returned in the result object (not thrown) and are always safe to show to the user:

const result = await createUser({ name: "", email: "bad" });

result.validationErrors;
// → { name: { _errors: ["Too short"] }, email: { _errors: ["Invalid email"] } }

Validation errors are produced in two ways:

1. Automatically — when Standard Schema validation fails on input or bind args
2. Manually — when you call returnValidationErrors() in your server code (e.g., "email already taken")

import { returnValidationErrors } from "next-safe-action";

export const signUp = actionClient
	.inputSchema(schema)
	.action(async ({ parsedInput }) => {
		const exists = await db.user.findByEmail(parsedInput.email);
		if (exists) {
			return returnValidationErrors(schema, {
				email: { _errors: ["Already registered"] },
			});
		}
		// ...
	});

See Input Validation for error shapes and Custom Validation Errors for advanced formatting.

Server errors

Server errors are unexpected failures, such as database timeouts, API failures, or bugs in your server code. By default, next-safe-action:

1. Catches the thrown error
2. Passes it to handleServerError (which you define in client options)
3. Returns the handler's return value as result.serverError

const actionClient = createSafeActionClient({
	handleServerError(e) {
		// This runs when any action throws an unexpected error
		console.error("Action error:", e.message);

		// What you return here becomes result.serverError on the client
		// Default: "Something went wrong"
		return e.message;
	},
});

Throwing errors instead of returning them

By default, validation and server errors are returned in the result object. You can opt into throwing them instead using boolean flags, which is useful when you want errors to propagate to an error boundary or a try/catch block.

throwServerError — action-level only. When enabled, server errors are re-thrown instead of being returned in result.serverError:

export const myAction = actionClient
	.inputSchema(schema)
	.action(
		async ({ parsedInput }) => {
			// ...
		},
		{
			throwServerError: true,
		}
	);

throwValidationErrors — available at both client and action level. When set at both levels, the action-level setting takes priority:

// Client-level: applies to all actions created from this client
const actionClient = createSafeActionClient({
	throwValidationErrors: true,
});

// Action-level: overrides the client setting for this specific action
export const myAction = actionClient
	.inputSchema(schema)
	.action(
		async ({ parsedInput }) => {
			// ...
		},
		{
			throwValidationErrors: true,
		}
	);

Framework errors

Framework errors are navigation events triggered by Next.js functions like redirect(), notFound(), forbidden(), and unauthorized(). These are special because they're not really "errors", but control flow mechanisms that Next.js uses to trigger navigation.

next-safe-action detects and handles these automatically:

import { redirect } from "next/navigation";

export const loginAction = actionClient
	.inputSchema(loginSchema)
	.action(async ({ parsedInput }) => {
		const user = await authenticate(parsedInput);
		// This triggers a redirect — not a normal return
		redirect("/dashboard");
	});

What happens with framework errors

1. On the server: The error is caught, identified as a framework error, and re-thrown so Next.js can handle the navigation
2. On the client: If using useAction, the hook detects the navigation and sets status to "hasNavigated" (instead of "hasSucceeded" or "hasErrored")
3. Callbacks: The onNavigation callback fires (instead of onSuccess or onError)

Navigation kinds

The navigationKind property tells you what type of navigation occurred:

const { execute } = useAction(myAction, {
	onNavigation: ({ navigationKind }) => {
		if (navigationKind === "redirect") {
			// Action triggered a redirect
		}
	},
});

See Framework Errors for advanced configuration.

Error handling summary

What's next?