Extends $ZodIssue to have a boolean telling if the error message was customized / provided via the error param.

[MrHus]

I'd like to be able to differentiate between custom errors and default error messages that originated from zod itself.

I translate all zod error manually to make them a bit more user friendly. I've written a function that unpacks the $ZodIssue
and renders custom error message by looking at the shape of ZodIssue, which is currently defined as:

{
  "origin": "array",
   "code": "too_small",
   "minimum": 1,
   "inclusive": true,
    "path": [
        "name"
     ],
     "message": "A pokemon must be at least part of one type"
}

It came from the following configuration:

export const pokemonSchema = z4.object({
  types: z4
    .array(
      z4.object({
        id: z4.number()
      })
    )
    .min(1, { error: 'A pokemon must be at least part of one type'})
    .max(2, { error: 'A pokemon can only be a part of a maximum of two types'})
});

Now I'd like to be able to differentiate between default zod error messages such as "Too small: expected string to have >=1 characters" and explicit programmer / developer provided ones such as the "pokemon types" errors above.

Would it be possible (and is it a a good idea?) to extend $ZodIssue with a boolean: customMessage.

When customMessage is true it was an error param provided by the developer, when false it came from zod.

Currently I'm forced to solve this via the following hack:

function isCustomErrorMessage(error: $ZodIssue): boolean {
  // too_small -> too small
  const errorLabel = error.code.split('_').join(' ');

  /* 
    If the error message itself does not contain the `errorLabel`
    it is MOST LIKELY a custom error message as provided by the developer.

    For example z.array().min(1, 'Pokemon requires at least one type')

     IMPORTANT: this only works if the custom error does not start with the errorLabel! So be careful!
  */
  return !error.message.toLocaleLowerCase().includes(errorLabel);
}

Of course the above code is brittle: if a developer passed in 'Too small: A pokemon must be at least part of one type' it will break.

Maybe there already exists an API to check this in zod I have not found it, please let me know.

[amasen02]

You don't need brittle substring matching for this, and there is a clean architectural reason why $ZodIssue does not carry a customMessage: boolean flag.

Why $ZodIssue doesn't retain the custom error flag

In Zod v4, $ZodIssue implements the Standard Schema spec (StandardSchemaV1.Issue). To keep the output object lightweight, JSON-serializable, and free of memory leaks (holding closures to parent schemas/AST nodes), Zod's finalizeIssue in packages/zod/src/v4/core/util.ts explicitly strips internal metadata (inst, schema, continue, input) when finalizing the issue into $ZodIssue:

// packages/zod/src/v4/core/util.ts
const full: any = {};
for (const k of Object.keys(iss)) {
  if (k === "inst" || k === "schema" || k === "continue" || k === "input" || k === "__proto__") continue;
  full[k] = (iss as any)[k];
}
full.path ??= [];
full.message = message;
return full;

Because of that cleanup, the returned $ZodIssue on result.error.issues only contains the finalized string in .message.

---

The Built-in Precedence (Why you don't need post-parse string inspection)

The key to solving this cleanly without heuristics is how finalizeIssue resolves message:

// packages/zod/src/v4/core/util.ts
const schemaError = iss.schema !== iss.inst ? iss.schema?._zod.def?.error : undefined;
const message = iss.message
  ? iss.message
  : (unwrapMessage(iss.inst?._zod.def?.error?.(iss as never)) ??
    unwrapMessage(schemaError?.(iss as never)) ??
    unwrapMessage(ctx?.error?.(iss as never)) ??
    unwrapMessage(config.customError?.(iss)) ??
    unwrapMessage(config.localeError?.(iss)) ??
    "Invalid input");

Notice the short-circuiting nullish coalescing (??):

1. Check-level error: iss.inst._zod.def.error (e.g. .min(1, { error: '...' })) evaluates first.
2. Schema-level error: schemaError (e.g. z.string({ error: '...' })) evaluates second.
3. Parse Context: ctx.error evaluates third.
4. Global Custom Error Map: config.customError (z.setErrorMap(...)) evaluates fourth.
5. Locale Default: config.localeError evaluates last.

Because of this order, if a developer supplied an explicit { error: '...' }, steps 4 and 5 are never even called. The resolution stops immediately at step 1.

---

Idiomatic Solution: Intercept at z.setErrorMap

Instead of parsing first and then inspecting strings in error.issues, hook your translation logic into z.setErrorMap (or a custom locale). Any issue that reaches this function is guaranteed to be a default Zod error that had no developer-supplied error override:

import { z } from "zod";

z.setErrorMap((issue) => {
  // If execution reaches here, NO check-level or schema-level `{ error: ... }` was provided!
  // Developer-defined errors (like your Pokemon message) were already resolved at step 1.
  
  switch (issue.code) {
    case "too_small":
      if (issue.origin === "array") {
        return `Must contain at least ${issue.minimum} item(s)`;
      }
      return `Minimum allowed value is ${issue.minimum}`;
    case "too_big":
      return `Maximum allowed value is ${issue.maximum}`;
    default:
      return undefined; // Falls back to default locale message if unhandled
  }
});

Verifying the Behavior

const pokemonSchema = z.object({
  types: z
    .array(z.object({ id: z.number() }))
    .min(1, { error: "A pokemon must be at least part of one type" }) // Custom developer message
    .max(2), // No custom message -> will use your translation error map!
});

// Case 1: Fails .min(1)
// Output message: "A pokemon must be at least part of one type" (developer override preserved)

// Case 2: Fails .max(2)
// Output message: "Maximum allowed value is 2" (translated by setErrorMap)

This completely removes the need for substring checking against error.code or guessing whether an error was customized.