How can I override Zod's default 'invalid_type' error message in a union schema using superRefine with RHF?

Below is one strategy for ensuring that your custom message is returned when the value is invalid:

1. Instead of relying on the union branch’s built‑in type error, you can move the check into a refine (or superRefine) at the array or nested‑object level. That way you can intercept the error and add your own message. For example, you could validate the overall array and then each object inside it. You can also override Zod’s default error messages globally if you prefer.

2. When you’re inside a refine or superRefine callback on an object (e.g. on your templateCode field) the current path is already set. There’s no need to prepend the key name manually unless you want to change it. In other words, if you’re inside the validation for the object that is the value of “templateCode” and add an issue without a “path” property, then that error will be reported at the “templateDefaults[0].templateCode” path (assuming that’s where it appears in your data).

Below is an example of one approach:

---

TYPESCRIPTCopied
import { z } from "zod";

// First, if you want to override the default type error globally, you can
// set a custom error map. (Optional.)
z.setErrorMap((issue, ctx) => {
  if (issue.code === z.ZodIssueCode.invalid_type && issue.received === "array") {
    return { message: "An option has to be selected" };
  }
  return { message: ctx.defaultError };
});

// Define the schema for templateCode as before.
const templateCodeSchema = z
  .object({
    tenantName: z.string(),
    tenantId: z.number(),
  })
  .passthrough()
  // Use superRefine to ensure that a valid option is selected.
  .superRefine((val, ctx) => {
    // Replace the condition with the one that applies to your logic.
    // For example, if an empty tenantName indicates nothing was selected:
    if (val.tenantName.trim() === "") {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: "An option has to be selected",
        // No need to specify the path here; it will be nested under `templateCode`.
      });
    }
  });

// Use the custom schema inside each array element.
// If you’re using a union for each array item (for example, a fallback object)
// the custom message in the first branch will be used for that branch only;
// otherwise you may wish to lift the refine to the array level.
const templateDefaultsSchema = z.array(
  z.union([
    z.object({
      templateCode: templateCodeSchema,
      // ... add other keys as needed
    }),
    // You may have another branch if necessary.
    z.object({
      // Alternative object shape
    }),
  ])
);

---

Explanation

• Custom Global Error Map:
  The call to z.setErrorMap() lets you replace the default error message for a given issue (in this case, if an invalid type “array” is received). This is one way to make sure that when Zod sees the wrong type you see “An option has to be selected” instead. This change applies globally so use it with care.

• Customizing via superRefine:
  In the templateCodeSchema we use superRefine so that if a condition occurs (for instance, if the string is empty) you call ctx.addIssue() with your own error message. Because you’re already inside the object’s validation, you don’t need to specify a custom path unless you want to fine‑tune where the error is shown.

• Path Consideration:
  When you’re in a refine or superRefine on the templateCode object, the current path is already set to that field. There is no need to include the key (["templateCode"]) explicitly unless you’re validating from a higher level (for example, if you run a custom check for the entire array). In the snippet above the error will automatically appear at templateDefaults[#].templateCode.

Using this approach, when you call await trigger() from React Hook Form, the validation should pick up your custom error message rather than the default “Expected object, received array” message.

Feel free to adjust the condition in superRefine and the error mapping to suit your application’s logic.