Zod v4: transform() runs even when .refine() fails, causing unexpected runtime errors

[AntoniusGolly]

In Zod v4, when chaining .refine() and .transform() on a schema, the .transform() function is still executed even if .refine() fails. This can lead to unexpected runtime exceptions (e.g. SyntaxError) during .parse() or .safeParse().

This behavior is surprising and different from v3 where transformation is expected to run only if validation succeeds.

The migration guide has no mentioning of it. Disclaimer, maybe I'm misusing the schema and can fix on my side.

Example

import { z } from 'zod'

const Schema = z.string()
  .refine((val) => {
    try {
      JSON.parse(val)
      return true
    } catch {
      return false
    }
  }, { message: 'must be valid JSON stringified array' })
  .transform((val) => JSON.parse(val)) // <-- this runs even if refine fails

// Invalid input: not JSON
const result = Schema.safeParse('this-is-not-json')
console.log(result)

Instead of returning { success: false, error: ZodError }, it throws:

Uncaught SyntaxError: Unexpected token h in JSON at position 1

[dosubot]

You're right—Zod v4 changed how .refine() and .transform() interact. In v4, .transform() always runs, even if .refine() fails, which can lead to runtime errors like SyntaxError if the input isn't valid for the transform. This is different from v3, where transforms would only run after successful validation. The change is due to Zod v4's new internal architecture, where refinements and transforms are layered as effects and transforms are applied regardless of previous validation errors unless an aborting issue is explicitly pushed (see code).

The v4 migration guide doesn't call out this change, but it's discussed in issues and the codebase (docs, issue). If you want to ensure transforms only run after validation, you can use .preprocess() or structure your schema so parsing and validation are separated. For more complex scenarios, use .check() (which replaces .superRefine() in v4) to aggregate validation and transformation logic, or configure your refinements to abort on failure.

If this answers your question, feel free to close the issue!

To reply, just mention @dosu.

---

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

[AntoniusGolly]

My question was more towards, is this considered a bug? It feels like it...

[dosubot]

This behavior in Zod v4 is a consequence of the new internal architecture, where transformations are applied regardless of previous validation errors unless an aborting issue is explicitly pushed. It's not documented as a deliberate user-facing feature, but rather appears to be an undocumented side effect of the new effect layering model introduced in v4. The migration guide and docs don't mention this change, and there are no explicit comments in the codebase or changelog calling it out as intentional or as a bug. So while it's not a "bug" in the sense of contradicting the current code or design, it is a surprising break from v3 safety and not a documented or justified feature for users migrating from v3 to v4. If you want transforms to only run after validation, you need to use aborting issues or restructure your schema logic. Reference

To reply, just mention @dosu.

---

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

[AntoniusGolly]

Will this be picked up by a human?
The description of @dosu is the definition of a bug. My problem is, that due to that behavior I'm not receiving a ZodError but a SyntaxError, without paths. In v3 this behavior was different.

I am aware of how to prevent this, but all fixes on our end is more verbose and the new behavior is unexpected.

Please, consider this a bug report, then.

[dosubot]

Thanks for clarifying—I've flagged this as a bug report and tagging @colinhacks for review.

To summarize: in Zod v4, .transform() runs even when .refine() fails, which can cause runtime errors like SyntaxError instead of returning a structured ZodError with paths. This is a change from v3 and is not documented in the migration guide. Other users have reported similar surprises with effect ordering and error handling in v4 (#4487, discussion #4706), but this specific behavior remains under-documented and unexpected for many migrating from v3.

This stems from Zod v4's new effect layering model, where transforms are applied regardless of previous validation errors unless an aborting issue is explicitly pushed. There’s no clear documentation marking this as an intentional user-facing change.

@colinhacks, could you clarify if this is intended or if it should be addressed as a bug? If you need more context or a runnable repro, let us know! If your concern is addressed, feel free to close the issue.

To reply, just mention @dosu.

---

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

[Botelho31]

Hey, you are correct in that this was previously default behaviour. But right now if you pass in abort: true on refine parameters next to message it will still do it the way you want.

import { z } from "zod";

const Schema = z.string()
  .refine((val) => {
    try {
      JSON.parse(val)
      return true
    } catch {
      return false
    }
  }, { message: 'must be valid JSON stringified array', abort: true }) <-- notice the new abort: true
  .transform((val) => JSON.parse(val)) // <-- this doesnt run now

// Invalid input: not JSON
const result = Schema.safeParse('this-is-not-json')
console.log(result)