●Change8

Migrating to Zod v4.4.0

Version v4.4.0 introduces 6 breaking changes. This guide details how to update your code.

Released: 4/29/2026

6
Breaking Changes
5
Migration Steps
17
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

z.tuplez.objectz.undefined()z.optional()z.mergez.refinez.toJSONSchemaz.base64z.cuidz.httpUrlz.recordz.string().transformz.discriminatedUnion().encodez.codecz.superRefinez.formatErrorz.treeifyError

Breaking Changes

●Issue #1

Object properties defined as `z.undefined()` are now treated as required keys (the key must be present, but its value can be `undefined`). If the key should be allowed to be absent, use `.optional()` on `z.undefined()`.

●Issue #2

`.merge()` now throws if the receiving schema has refinements, due to ambiguous behavior. Prefer `.extend()` or `.safeExtend()` for object composition.

●Issue #3

JSON Schema conversion (`z.toJSONSchema()`) no longer includes redundant `id` fields in `$defs` entries. Consumers reading these internal fields directly may break.

●Issue #4

Base64 validation now rejects whitespace (e.g., "Zm 9v" is invalid).

●Issue #5

CUID validation through `z.cuid()` has been tightened, and CUID v1 is deprecated.

●Issue #6

HTTP URL validation (`z.httpUrl()`) now rejects malformed URLs like "https:/example.com" which were previously accepted after normalization by the underlying `URL` constructor.

Migration Steps

  1. 1
    If you relied on object properties defined as `z.undefined()` being optional (i.e., the key could be missing), change the schema to `z.undefined().optional()`.
  2. 2
    If you were using `.merge()` where the receiver schema had refinements, switch to `.extend()` or `.safeExtend()`.
  3. 3
    Review code that parses base64 strings if it relied on whitespace being ignored.
  4. 4
    Review code that parses HTTP URLs if it relied on malformed inputs like "https:/example.com" being accepted.
  5. 5
    If you snapshot ZodError outputs, be aware that error paths for unions and discriminated unions may have changed slightly for correctness.

Release Summary

This minor release focuses heavily on correctness and soundness fixes, particularly around tuple parsing defaults, object property requirements when using z.undefined(), and stricter string validation rules. Several changes are potentially breaking for code relying on previously ambiguous input handling.

Need More Details?

View the full release notes and all changes for Zod v4.4.0.

View Full Changelog