next-safe-action
API Reference

Error Classes

next-safe-action exports several error classes that are thrown during action execution. You can use these in handleServerError or try/catch blocks to identify specific error types.

All error classes are imported from the main entry point:

import {
	ActionValidationError,
	ActionBindArgsValidationError,
	ActionMetadataValidationError,
	ActionOutputDataValidationError,
} from "next-safe-action";

ActionValidationError

Thrown when input validation fails and throwValidationErrors is enabled (either at the client level or per action). Contains the shaped validation errors (after handleValidationErrorsShape is applied).

class ActionValidationError<CVE> extends Error {
	validationErrors: CVE;
}

Prop

Type

// Enable throwing per action
export const myAction = actionClient.action(
	async ({ parsedInput }, { throwValidationErrors }) => {
		throwValidationErrors(schema, {
			email: { _errors: ["Already registered"] },
		});
	}
);

// Or enable globally
const actionClient = createSafeActionClient({
	throwValidationErrors: true,
});

// Catch in handleServerError
const actionClient = createSafeActionClient({
	throwValidationErrors: true,
	handleServerError: (error) => {
		if (error instanceof ActionValidationError) {
			// error.validationErrors is available
			return "Validation failed";
		}
		return DEFAULT_SERVER_ERROR_MESSAGE;
	},
});

ActionBindArgsValidationError

Thrown internally when bind argument validation fails. This error is caught by the action builder and the validation errors are returned in the result.

class ActionBindArgsValidationError extends Error {
	validationErrors: unknown[];
}

Prop

Type

This error is handled internally by the action builder. You typically don't need to catch it yourself unless you're building custom error handling in handleServerError.

ActionMetadataValidationError

Thrown when the metadata provided via .metadata() doesn't match the schema defined by defineMetadataSchema. This is a developer error, meaning the metadata value doesn't conform to the schema.

class ActionMetadataValidationError<MDS extends StandardSchemaV1 | undefined> extends Error {
	validationErrors: ValidationErrors<MDS>;
}

Prop

Type

ActionOutputDataValidationError

Thrown when the action's return value doesn't match the schema defined by .outputSchema(). This is a developer error, meaning the server code is returning data that doesn't conform to the output schema.

class ActionOutputDataValidationError<DS extends StandardSchemaV1 | undefined> extends Error {
	validationErrors: ValidationErrors<DS>;
}

Prop

Type

Error handling patterns

Identifying errors in handleServerError

import {
	ActionValidationError,
	ActionMetadataValidationError,
	ActionOutputDataValidationError,
} from "next-safe-action";

const actionClient = createSafeActionClient({
	throwValidationErrors: true,
	handleServerError: (error) => {
		if (error instanceof ActionValidationError) {
			return "Please check your input.";
		}
		if (error instanceof ActionMetadataValidationError) {
			console.error("Developer error: invalid metadata", error.validationErrors);
			return "Internal error";
		}
		if (error instanceof ActionOutputDataValidationError) {
			console.error("Developer error: invalid output", error.validationErrors);
			return "Internal error";
		}
		return "Something went wrong.";
	},
});

See also

Validation Utilities

API reference for validation error utility functions and constants.

Hooks API

API reference for useAction, useOptimisticAction, and useStateAction hooks.

On this page

ActionValidationErrorActionBindArgsValidationErrorActionMetadataValidationErrorActionOutputDataValidationErrorError handling patternsIdentifying errors in handleServerErrorSee also