Zod v4 Migration Checklist: API Changes and Dependabot Gotchas

Published: 2026-06-28

Dependabot opened a dependency upgrade PR — Zod 3.25.76 → 4.4.3 — in the same batch as a TypeScript 6.0 upgrade in the dev-tooling group.

Most of the breaking changes were straightforward. The following ones weren’t.

This is a demo project — I merged and fixed what broke, which is how most of this ended up documented.

ZodError.errors Alias Removed — Use .issues

The most visible API change in Zod v4 is the removal of the .errors alias on ZodError. This v3 pattern breaks on upgrade:

// v3
catch (e) {
  if (e instanceof ZodError) {
    console.log(e.errors);
  }
}

In v4, that line produces: Property 'errors' does not exist on type 'ZodError'.

The .errors alias has been removed. .issues was the primary property in v3 and remains so in v4:¹

// v4
catch (e) {
  if (e instanceof ZodError) {
    console.log(e.issues);
  }
}

No behavior change — the data is the same array. Before upgrading, search the codebase for every .errors access on ZodError instances and update them to .issues.

parse() Return Type Changed — and It Compounds with TypeScript 6

In Zod v3, schema.parse() returned Output directly. In Zod v4, it returns core.output<this> — a this-polymorphic conditional type.²

For most call sites this is invisible. The failure mode is specific: ReturnType<typeof Schema.parse> collapses to unknown when combined with TypeScript 6.0’s inference changes. This is covered in detail in TypeScript 6 + Zod v4: ReturnType Collapses to unknown.

The migration fix applies regardless of the TypeScript version: stop using ReturnType<typeof Schema.parse> to derive the output type. Use z.infer<> instead:

// Before — fragile with Zod v4
type AlertDto = ReturnType<typeof AlertSchema.parse>;

// After — stable
type AlertDto = z.infer<typeof AlertSchema>;

Grep before merging:

grep -r "ReturnType<typeof" src/ --include="*.ts"

Any match involving a Zod schema method (parse, safeParse) needs to be replaced.

Dependabot Group Splits Hide Compound Failures

Dependabot split the TypeScript and Zod upgrades into separate PRs. Each PR’s CI run passed independently — type inference failures aren’t compile errors until they cause a downstream type mismatch.

The combination of TypeScript 6.0 and Zod v4 only became visible during the production build, after both had merged. By then, isolating which PR introduced each error was manual work.

Two practices that would have caught this earlier:

Read the CHANGELOG for every version bump, not just major ones. Dependabot marks major upgrades clearly, but minor bumps can contain runtime-breaking changes that produce no TypeScript error and pass CI. When zod goes from 3.x to 4.x, treat it as a mandatory review before merging.

Run tsc --noEmit after each group merges, before merging the next. Type-level regressions are invisible to tests. A type-check pass between PRs narrows the search space before failures compound.

Migration Checklist

Before merging a Zod v3 → v4 upgrade:

• Search for .errors on ZodError instances → update to .issues
• Search for ReturnType<typeof schema.parse> or ReturnType<typeof schema.safeParse> → replace with z.infer<typeof schema> or a named exported type
• If TypeScript 6.0 is also in scope: read the ReturnType interaction post before merging
• For grouped Dependabot PRs: read the CHANGELOG for each package individually
• Run tsc --noEmit after each major bump group merges

Further Reading

• Zod v4 migration guide — the authoritative list of breaking changes, including the removal of .errors, ZodType generic restructure, and the full parse() signature change.
• TypeScript 6 + Zod v4: ReturnType collapses to unknown — detailed walkthrough of why ReturnType<typeof Schema.parse> becomes unknown when both upgrades land together.
• TypeScript 6.0: 3 Breaking Changes That Hit My NestJS Project — the TS6 changes that came with the same upgrade batch: rootDir enforcement, baseUrl deprecation, and strictPropertyInitialization.