[Bug] Unexpected Continue Pipe since Zod v4 when using ctx.addIssue

[qoomon]

Sice v4 ctx.addIssue does continue by default.

In version 3 following transformer does not continue the pipe. In version 4 it does.

If I replace ctx.addIssue with ctx.issues.push it works as expected, see below examples

Zod v4 with ctx.addIssue - Unexpected behavior: does continue pipe

import {z} from 'zod';

export const JsonTransformer = z.string().transform((val, ctx) => {
  try {
    return JSON.parse(val);
  } catch (error: unknown) {
    ctx.addIssue({
      code: 'custom',
      message: (error as { message?: string }).message,
    });
    return z.NEVER;
  }
});


const result = await JsonTransformer.pipe(z.object({
  foo: z.string(),
})).safeParseAsync("invalid");
console.log("error:", result.error?.issues)

Output

 [
  {
    code: 'custom',
    message: `Unexpected token 'i', "invalid" is not valid JSON`,
    path: []
  },
  {
    expected: 'string',
    code: 'invalid_type',
    path: [ 'foo' ],
    message: 'Invalid input: expected string, received undefined'
  }
]

Zod v4 with ctx.addIssue - Works as expected

import {z} from 'zod';

export const JsonTransformer = z.string().transform((val, ctx) => {
  try {
    return JSON.parse(val);
  } catch (error: unknown) {
     ctx.issues.push({
      code: 'custom',
      message: (error as { message?: string }).message,
      input: val,
    });
    return z.NEVER;
  }
});


const result = await JsonTransformer.pipe(z.object({
  foo: z.string(),
})).safeParseAsync("invalid");
console.log("error:", result.error?.issues)

Output

 [
  {
    code: 'custom',
    message: `Unexpected token 'i', "invalid" is not valid JSON`,
    path: []
  }
]

[dosubot]

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

In Zod v4, ctx.addIssue is non-fatal by default—so even if you add an issue and return z.NEVER, the pipe continues and you may see additional errors from downstream schemas. To replicate the v3 behavior (where adding an issue halts the pipe), set fatal: true in your issue object:

ctx.addIssue({
  code: 'custom',
  message: (error as { message?: string }).message,
  fatal: true,
});
return z.NEVER;

This change is intentional and gives you more control over error handling in v4. Only ctx.addIssue supports the fatal flag; ctx.issues.push just records the issue and doesn't affect control flow. For more details, see the relevant PR and tests.

If this solves your problem, please close the issue. If you need more help, a minimal reproduction is always appreciated!

To reply, just mention @dosu.

---

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

[qoomon]

@colinhacks could you help me out, if this behaviour is intended or not?

[qoomon]

@dosu Yes, ctx.issues.push actually does effect the control flow and behaves like ctx.addIssuewith the fatal: true. I think this is unexpected because both methods should add an issue the same way. Nobody expect a different behaviour between add and push method

[dosubot]

You're right—ctx.addIssue and ctx.issues.push do not behave the same way in Zod v4. This is due to how control flow is managed: ctx.addIssue sets the continue property to true by default (unless you set fatal: true), so the pipe continues unless you explicitly make the issue fatal. In contrast, ctx.issues.push does not set continue, so issues pushed directly are treated as fatal and halt the pipe by default. This difference is a result of implementation details, not a documented or supported part of the public API—directly mutating ctx.issues is not recommended and may lead to unpredictable behavior. The intended and supported way to add issues is always through ctx.addIssue, which gives you explicit control over error handling and pipe continuation. For predictable results, use ctx.addIssue and set fatal: true if you want to halt the pipe, as described in the codebase.

If this clears things up, please close the issue!

To reply, just mention @dosu.

---

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

[qoomon]

directly mutating ctx.issues is not recommended

@dosu you are wrong. Actually ctx.issues.push seems to be the recommended way, because it is used in every example at https://zod.dev/api

[dosubot]

You're right—ctx.issues.push is documented and supported in Zod v4, and it's used throughout the official docs for reporting issues in .transform and .check methods. The v4 changelog even notes that .addIssue() and .addIssues() are deprecated, and recommends pushing directly to the issues array if needed (docs, changelog).

The main difference: ctx.issues.push adds a fatal issue by default (halts the pipe), while ctx.addIssue is non-fatal unless you set fatal: true (so the pipe continues unless you opt out) (source). Use whichever matches your control flow needs—both are public and supported APIs.

If this clears things up, feel free to close the issue!

To reply, just mention @dosu.

---

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

[qoomon]

@dosu but why the behaviour change for .addIssues() especially if it's deprecated. I still think thats an unintended breaking change. WDYT @colinhacks

[dosubot]

The change in .addIssues() behavior in Zod v4 is a side effect of a deeper refactor around error handling and control flow. In v3, .addIssues() just appended issues and didn't control validation flow. In v4, both .addIssue() and .addIssues() are deprecated and simply push to the issues array, but the semantics of how issues affect control flow changed: pushing to the array is now always interpreted as fatal (halts the pipe), while .addIssue() gives you explicit control via the fatal flag. This shift is not called out as a breaking change in the v4 changelog—it's a consequence of the new architecture for error handling and pipe continuation, not a targeted change to .addIssues() itself. The docs recommend pushing directly to the array if needed, but the migration impact for users relying on v3's behavior isn't clearly documented (changelog, v4 errors.ts).

Tagging @colinhacks for input on whether this was intended and if migration docs should clarify this subtle but impactful change.

To reply, just mention @dosu.

---

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