Add a .message() method to Zod schemas for a default error message

[jrTilak]

Description:

Currently, Zod allows us to specify error messages for each validation method like min, max, etc. However, there is no way to specify a default error message for a field that applies when any validation fails.

For example, consider this schema:

const guestUserSchema = z.object({
  name: z
    .string({
      invalid_type_error: "Invalid name",
      required_error: "Name is required",
    })
    .min(3, {
      message: "Name must be at least 3 characters long",
    })
    .max(20, {
      message: "Name must be at most 20 characters long",
    }),
  username: z.string().min(3).max(20).startsWith("guest_"),
  method: z.array(z.literal("guest")).default(["guest"]),
});

I would like to be able to specify a default error message for the name field that is shown when any validation fails, like this:

const guestUserSchema = z.object({
  name: z
    .string()
    .min(3)
    .max(20)
    .message("Name must be between 3 to 20 characters"),
  username: z.string().min(3).max(20).startsWith("guest_"),
  method: z.array(z.literal("guest")).default(["guest"]),
});

In this example, the .message() method would set a default error message for the name field that is shown when the min or max validation fails.

Use Case:

This feature would be useful for providing more general error messages when any validation fails for a field, instead of having to specify an error message for each validation method.

Proposed Solution:

Add a .message() method to Zod schemas that sets a default error message for a field. This message would be shown when any validation fails for the field.

Alternatives Considered:

An alternative is to use the .refine() method to add a custom validation that always passes but provides a custom error message when any other validation fails. However, this is more of a workaround than a solution, and it would be more convenient to have a built-in method for this purpose.

[JacobWeisenburger]

Is this what you are looking for?

const guestUserSchema = z.object( {
    name: z
        .string( { errorMap: () => ( { message: 'Name must be between 3 to 20 characters' } ) } )
        .min( 3 )
        .max( 20 )
} )

If you found my answer satisfactory, please consider supporting me. Even a small amount is greatly appreciated. Thanks friend! 🙏
https://github.com/sponsors/JacobWeisenburger

[jrTilak]

Yeah, Exactly! 🔥❤️

[condeguru]

How can we do this using ZOD 4? errorMap doesnt exist anymore and error will not give us a default error message

[mklnz]

Looking for an answer for Zod 4 too

[BAHAA-THE-KING]

Also using v4 and had the same issue
I think that .message() is cleaner and more elegant