Will addIssue be deprecated for superRefine ctx variable?

[MasterOdin]

From the docs for superRefine:

const UniqueStringArray = z.array(z.string()).superRefine((val, ctx) => {
  if (val.length > 3) {
    ctx.addIssue({
      code: "too_big",
      maximum: 3,
      origin: "array",
      inclusive: true,
      message: "Too many items 😡",
      input: val,
    });
  }
 
  if (val.length !== new Set(val).size) {
    ctx.addIssue({
      code: "custom",
      message: `No duplicates allowed.`,
      input: val,
    });
  }
});

It uses the .addIssue function to add the issue. Doing a similar thing was deprecated for errors, will a similar thing happen for the ctx variable?

[dosubot[bot]]

Hi @MasterOdin! I'm Dosu, a bot trained on Zod's codebase & issues, and I'm helping the Zod team.

ctx.addIssue() in .superRefine() is not currently deprecated. As of November 2, 2026, the refinement context declares it without an @deprecated annotation and implements it as part of .superRefine(). [1]

The changelog entry applies specifically to ZodError.addIssue() and ZodError.addIssues(). Those methods are explicitly deprecated in favor of pushing directly to err.issues; they are separate from the refinement-context method. [2]

So there's no need to change your example on account of that changelog entry. I can't confirm future deprecation plans; @colinhacks would need to speak to those.

Feel free to close the discussion if that answers your question.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[CharlieJamesGwapo]

The deprecation in the v4 changelog is only about the methods on ZodError (err.addIssue() / err.addIssues()). In the current source those are tagged @deprecated in packages/zod/src/v4/classic/errors.ts, but addIssue on the refinement context isn't: it's declared on $RefinementCtx in packages/zod/src/v4/core/api.ts with no deprecation tag.

Some context that might help you decide what to write going forward:

• In v4, .superRefine() is built on top of .check(). The ctx.addIssue() you get there is a small wrapper that fills in defaults (code: "custom", input, continue) and then pushes onto ctx.issues. The source comments describe it as kept for Zod 3 backwards compatibility.
• The ctx passed to superRefine also exposes issues, so you can push directly if you prefer:

z.array(z.string()).superRefine((val, ctx) => {
  if (val.length !== new Set(val).size) {
    ctx.issues.push({ code: "custom", message: "No duplicates allowed.", input: val });
  }
});

• The equivalent with .check(), which the docs describe as the more low-level, more verbose API:

z.array(z.string()).check((ctx) => {
  if (ctx.value.length !== new Set(ctx.value).size) {
    ctx.issues.push({ code: "custom", message: "No duplicates allowed.", input: ctx.value });
  }
});

Only Colin can speak to long-term plans, but as of today ctx.addIssue in superRefine isn't deprecated, and both forms above produce the same issues (checked with zod 4.6.7).