●Change8

Migrating to Zod v4.1.0

Version v4.1.0 introduces 1 breaking change. This guide details how to update your code.

Released: 8/23/2025

1
Breaking Changes
3
Migration Steps
10
Affected Symbols

⚠️ Check Your Code

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

z.codecz.decodez.encodez.hashZodObject.safeExtendZodObject.extendZodSchema.decodeZodSchema.encodeZodSchema.safeDecodeZodSchema.safeEncode

Breaking Changes

●Issue #1

Refinements on base schemas are no longer silently dropped when using .extend(). In Zod 4.1, attempting to extend a refined object now throws an error to prevent unexpected behavior, directing users toward .safeExtend() instead.

Migration Steps

  1. 1
    Replace .extend() with .safeExtend() if you need to preserve refinements from the base object schema.
  2. 2
    Use z.decode(schema, data) instead of schema.decode(data) if using Zod Mini to keep bundle sizes optimized.
  3. 3
    Update any manual bi-directional logic to use the new z.codec() API for better type safety and consistency.

Release Summary

Zod 4.1 introduces Codecs for bi-directional data transformation and .safeExtend() for type-safe object extensions that preserve refinements. It also adds a new z.hash() validator and strongly-typed decode/encode methods.

Need More Details?

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

View Full Changelog