Zod · all subjects

error customization

9 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Customize error messages on refinements and checks

The .refine() method accepts an object parameter with an error property to customize the error message. The error property can be a string or a function that receives the issue object. For example: z.string().refine((val) => val.length > 8, { error: 'Too short!' }) or z.string().refine((val) => val.length > 8, { error: (iss) => `Too short: "${iss.input}"` }).

z.custom() error customization

The second argument to z.custom() can customize error message and other options. It works the same way as the params parameter of .refine(): z.custom<Type>((val) => ..., "custom error message").

refine() path parameter customizes error location

The path parameter in .refine() allows specifying exactly which field an error is attached to. In the password example: path: ["confirm"] attaches the error to the confirm field even though the validation checked both fields.

z.config() configures locales for error messages

Use z.config(z.locales.en()) to configure English locale (default). Zod 4 introduces a locales API for globally translating error messages into different languages.

Unified error parameter in Zod 4

Zod 4 replaces message, invalid_type_error, required_error, and errorMap with a single unified error parameter. This can be a string or a function that receives an issue object.

Replace message with error in refinements

For refinement constraints like min(), replace: z.string().min(5, { message: 'Too short.' }); with: z.string().min(5, { error: 'Too short.' });

Replace invalid_type_error and required_error with error function

Replace z.string({ required_error: 'This field is required', invalid_type_error: 'Not a string' }); with: z.string({ error: (issue) => issue.input === undefined ? 'This field is required' : 'Not a string' });

Replace errorMap with error function

Replace z.string({ errorMap: (issue, ctx) => { if (issue.code === 'too_small') { return { message: `Value must be >${issue.minimum}` }; } return { message: ctx.defaultError }; } }); with: z.string({ error: (issue) => { if (issue.code === 'too_small') { return `Value must be >${issue.minimum}`; } } });

message parameter deprecated in favor of error

The message parameter is still supported in Zod 4 but is deprecated. Use the error parameter instead.

Give your agent this brain