Returning an other data type as error message

[saman2007]

Hello guys.
In my Next.js project, I implemented internationalization by myslef (without using any packages). And I use zod with react-hook-form.
Here is the problem:
my locale messages can be like this: "Text must be at least {n} character(s)"
and with t method, i can get the text base on the locale like this: t('key', {n: 1})
But when I tried to make some error messages in zod config like this: {message: {key: "key", data: {somedata: data}}}, I realized that the type of error messages in zod, is either string or null.
So do you have any idea about how I can change the error message format in zod config? I remember that I implemented this kind of error messages using yup but with zod, I have no idea about how to do it.
Here is what I want to do but the declared types for zod, cause TS error and I can't simply ignore them because there could be something important about error types in Zod’s internal code internal code that I don't know about.

// zodConfig.ts
import { z } from "zod";

z.config({
  customError: (iss) => {
    switch (iss.code) {
      case "too_small":
        return { message: { key: "too_small", data: { n: iss.minimum } } };

      default:
        return iss.message;
    }
  },
});

export { z };

And I want to use error messages in my form fields that are with validation, like this:

const InputRHF = ({
  name,
  ...props
}: React.ComponentProps<"input"> & { name: string }) => {
  const { register } = useFormContext();
  const { errors } = useFormState({ name });

  const params = useParams<Params>();
  const { t } = getTranslations(["zod-errors"], params);

  const error = errors[name]?.message as
    | { key: string; data: Record<string, string | number> }
    | undefined;

  return (
    <>
      <InputUI
        aria-invalid={!!error}
        {...props}
        {...register(name, {
          onBlur: props?.onBlur,
          onChange: props?.onChange,
        })}
      />
      <FieldError error={error ? t(`zod-errors.${error.key}`, error.data) : undefined} />
    </>
  );
};

One solution that I've found is to use JSON.stringify and JSON.parse but it feels like a workaround and I would prefer not to use it until I have no choice.

[dosubot]

Hi @saman2007! I'm Dosu and I’m helping the zod team.

Zod enforces error messages to be strings for compatibility and simplicity, especially with libraries like react-hook-form. This is a deliberate design decision—while Zod doesn't care about the runtime type of issue.message, the TypeScript types will remain string, and returning objects will cause TS errors (maintainer comment).

For internationalization, the recommended approach is to use error codes or parameters in the string message, then extract those from the issue object for translation. For example, you can set the message to something like "too_small:{n}" and parse out the code and parameters in your UI layer. Some users solve this by using parameters in the message string, not structured objects (discussion).

If you need to propagate structured error data, you can use Zod's error formatting utilities like flattenError, formatError, or treeifyError with a custom mapper function. These now support generic types for error messages, so you can map each issue to an object post-validation (PR #5278). However, this is only available after parsing, not in the schema definition or error map.

If you want to avoid JSON.stringify/parse, you could use a convention like encoding your error code and parameters in the string, then parsing them in your form component. For example:

z.config({
  customError: (iss) => {
    switch (iss.code) {
      case "too_small":
        return `too_small|n=${iss.minimum}`;
      default:
        return iss.message;
    }
  },
});

Then, in your UI, split and parse the string to get the code and parameters for translation.

For more details, see the error customization docs and error formatting docs.

If this answers your question, feel free to close the issue! If you need more help, a minimal reproduction would be helpful.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}