> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/colinhacks/zod/llms.txt
> Use this file to discover all available pages before exploring further.
# Zod v4 Changelog
> Complete changelog and migration guide for upgrading from Zod 3 to Zod 4
This migration guide lists the breaking changes in Zod 4 in order of highest to lowest impact. To learn more about the performance enhancements and new features of Zod 4, read the introductory post.
## Installation
To upgrade to Zod 4:
```bash theme={null}
npm install zod@^4.0.0
```
Many of Zod's behaviors and APIs have been made more intuitive and cohesive. The breaking changes described in this document often represent major quality-of-life improvements for Zod users. I strongly recommend reading this guide thoroughly.
**Note** — Zod 3 exported a number of undocumented quasi-internal utility types and functions that are not considered part of the public API. Changes to those are not documented here.
**Unofficial codemod** — A community-maintained codemod [`zod-v3-to-v4`](https://github.com/nicoespeon/zod-v3-to-v4) is available.
## Breaking Changes
Zod 4 standardizes the APIs for error customization under a single, unified `error` param. Previously Zod's error customization APIs were fragmented and inconsistent.
### Deprecates `message` parameter
Replaces `message` param with `error`. The old `message` parameter is still supported but deprecated.
```ts theme={null}
z.string().min(5, { error: "Too short." });
```
```ts theme={null}
z.string().min(5, { message: "Too short." });
```
### Drops `invalid_type_error` and `required_error`
The `invalid_type_error` / `required_error` params have been dropped. These can now be cleanly represented with the new `error` parameter.
```ts theme={null}
z.string({
error: (issue) => issue.input === undefined
? "This field is required"
: "Not a string"
});
```
```ts theme={null}
z.string({
required_error: "This field is required",
invalid_type_error: "Not a string",
});
```
### Drops `errorMap`
This is renamed to `error`. Error maps can also now return a plain `string` (instead of `{message: string}`). They can also return `undefined`, which tells Zod to yield control to the next error map in the chain.
```ts theme={null}
z.string().min(5, {
error: (issue) => {
if (issue.code === "too_small") {
return `Value must be >${issue.minimum}`
}
},
});
```
```ts theme={null}
z.string({
errorMap: (issue, ctx) => {
if (issue.code === "too_small") {
return { message: `Value must be >${issue.minimum}` };
}
return { message: ctx.defaultError };
},
});
```
### Updates issue formats
The issue formats have been dramatically streamlined.
```ts theme={null}
import * as z from "zod"; // v4
type IssueFormats =
| z.core.$ZodIssueInvalidType
| z.core.$ZodIssueTooBig
| z.core.$ZodIssueTooSmall
| z.core.$ZodIssueInvalidStringFormat
| z.core.$ZodIssueNotMultipleOf
| z.core.$ZodIssueUnrecognizedKeys
| z.core.$ZodIssueInvalidValue
| z.core.$ZodIssueInvalidUnion
| z.core.$ZodIssueInvalidKey // new: used for z.record/z.map
| z.core.$ZodIssueInvalidElement // new: used for z.map/z.set
| z.core.$ZodIssueCustom;
```
### Changes error map precedence
The error map precedence has been changed to be more consistent. An error map passed into `.parse()` no longer takes precedence over a schema-level error map.
```ts theme={null}
const mySchema = z.string({ error: () => "Schema-level error" });
// in Zod 3
mySchema.parse(12, { error: () => "Contextual error" }); // => "Contextual error"
// in Zod 4
mySchema.parse(12, { error: () => "Contextual error" }); // => "Schema-level error"
```
### Deprecates `.format()` and `.flatten()`
The `.format()` and `.flatten()` methods on `ZodError` have been deprecated. Instead use the top-level `z.treeifyError()` function.
### Deprecates `.addIssue()` and `.addIssues()`
Directly push to `err.issues` array instead:
```ts theme={null}
myError.issues.push({
// new issue
});
```
### No infinite values
`POSITIVE_INFINITY` and `NEGATIVE_INFINITY` are no longer considered valid values for `z.number()`.
### `.safe()` no longer accepts floats
In Zod 4, `z.number().safe()` is deprecated. It now behaves identically to `.int()`, meaning it no longer accepts floats.
### `.int()` accepts safe integers only
The `z.number().int()` API no longer accepts unsafe integers (outside the range of `Number.MIN_SAFE_INTEGER` and `Number.MAX_SAFE_INTEGER`).
### Deprecates `.email()` etc
String formats are now represented as subclasses of `ZodString`. These APIs have been moved to the top-level `z` namespace.
```ts theme={null}
z.email();
z.uuid();
z.url();
z.emoji();
z.base64();
z.base64url();
z.nanoid();
z.cuid();
z.cuid2();
z.ulid();
z.ipv4();
z.ipv6();
z.cidrv4();
z.cidrv6();
z.iso.date();
z.iso.time();
z.iso.datetime();
z.iso.duration();
```
```ts theme={null}
z.string().email();
z.string().uuid();
z.string().url();
z.string().emoji();
// etc.
```
### Stricter `.uuid()`
The `z.uuid()` now validates UUIDs more strictly against the RFC 9562/4122 specification. For a more permissive validator, use `z.guid()`.
```ts theme={null}
z.uuid(); // RFC 9562/4122 compliant UUID
z.guid(); // any 8-4-4-4-12 hex pattern
```
### Drops `z.string().ip()` and `z.string().cidr()`
```ts theme={null}
z.ipv4(); // IPv4 addresses
z.ipv6(); // IPv6 addresses
z.cidrv4(); // IPv4 CIDR ranges
z.cidrv6(); // IPv6 CIDR ranges
```
```ts theme={null}
z.string().ip();
z.string().cidr();
```
The input type of all `z.coerce` schemas is now `unknown`.
```ts theme={null}
const schema = z.coerce.string();
type schemaInput = z.input;
// Zod 3: string;
// Zod 4: unknown;
```
### `.default()` updates
The application of `.default()` has changed. If the input is `undefined`, `ZodDefault` short-circuits and returns the default value. The default value must be assignable to the output type.
```ts theme={null}
const schema = z.string()
.transform(val => val.length)
.default(0); // must be a number
schema.parse(undefined); // => 0
```
```ts theme={null}
const schema = z.string()
.transform(val => val.length)
.default("tuna"); // must be a string
schema.parse(undefined); // => 4
```
### New `.prefault()` API
To replicate the old behavior, use the new `.prefault()` API ("pre-parse default"):
```ts theme={null}
const schema = z.string()
.transform(val => val.length)
.prefault("tuna");
schema.parse(undefined); // => 4
```
### Defaults applied within optional fields
Defaults inside properties are applied, even within optional fields. This may cause breakage in code paths that rely on key existence.
```ts theme={null}
const schema = z.object({
a: z.string().default("tuna").optional(),
});
schema.parse({});
// Zod 4: { a: "tuna" }
// Zod 3: {}
```
### Deprecates `.strict()` and `.passthrough()`
Use the top-level `z.strictObject()` and `z.looseObject()` functions instead:
```ts theme={null}
z.strictObject({ name: z.string() });
z.looseObject({ name: z.string() });
```
```ts theme={null}
z.object({ name: z.string() }).strict();
z.object({ name: z.string() }).passthrough();
```
### Deprecates `.merge()`
The `.merge()` method has been deprecated in favor of `.extend()`:
```ts theme={null}
// Deprecated
const ExtendedSchema = BaseSchema.merge(AdditionalSchema);
// Recommended
const ExtendedSchema = BaseSchema.extend(AdditionalSchema.shape);
// Best performance
const ExtendedSchema = z.object({
...BaseSchema.shape,
...AdditionalSchema.shape,
});
```
### Drops `.deepPartial()`
This long-deprecated method has been removed with no direct replacement.
### Changes `z.unknown()` optionality
```ts theme={null}
const mySchema = z.object({
a: z.any(),
b: z.unknown()
});
// Zod 3: { a?: any; b?: unknown };
// Zod 4: { a: any; b: unknown };
```
### `z.nativeEnum()` deprecated
The `z.nativeEnum()` function is now deprecated. Use `z.enum()` instead, which now supports enum-like inputs:
```ts theme={null}
enum Color {
Red = "red",
Green = "green",
Blue = "blue",
}
const ColorSchema = z.enum(Color); // ✅
```
### Removes redundant enum APIs
```ts theme={null}
ColorSchema.enum.Red; // ✅ => "Red" (canonical API)
ColorSchema.Enum.Red; // ❌ removed
ColorSchema.Values.Red; // ❌ removed
```
### Changes `.nonempty()` type
```ts theme={null}
const NonEmpty = z.array(z.string()).nonempty();
type NonEmpty = z.infer;
// Zod 3: [string, ...string[]]
// Zod 4: string[]
```
For the old behavior, use `z.tuple()` with a rest argument:
```ts theme={null}
z.tuple([z.string()], z.string());
// => [string, ...string[]]
```
### API restructure
The result of `z.function()` is no longer a Zod schema. It acts as a standalone "function factory" for defining Zod-validated functions.
```ts theme={null}
const myFunction = z.function({
input: [z.object({
name: z.string(),
age: z.number().int(),
})],
output: z.string(),
});
myFunction.implement((input) => {
return `Hello ${input.name}, you are ${input.age} years old.`;
});
```
```ts theme={null}
const myFunction = z.function()
.args(z.object({
name: z.string(),
age: z.number().int(),
}))
.returns(z.string());
myFunction.implement((input) => {
return `Hello ${input.name}, you are ${input.age} years old.`;
});
```
### Adds `.implementAsync()`
For async functions, use the new `implementAsync()` method:
```ts theme={null}
myFunction.implementAsync(async (input) => {
return `Hello ${input.name}, you are ${input.age} years old.`;
});
```
### Ignores type predicates
Passing a type predicate as a refinement function no longer narrows the type.
```ts theme={null}
const mySchema = z.unknown().refine((val): val is string => {
return typeof val === "string"
});
type MySchema = z.infer;
// Zod 3: `string`
// Zod 4: still `unknown`
```
### Drops `ctx.path`
The `ctx.path` property is no longer available in refinement functions:
```ts theme={null}
z.string().superRefine((val, ctx) => {
ctx.path; // ❌ no longer available
});
```
### Drops function as second argument
The following overload has been removed:
```ts theme={null}
// ❌ No longer supported
const longString = z.string().refine(
(val) => val.length > 10,
(val) => ({ message: `${val} is not more than 10 characters` })
);
```
### Drops single argument usage
```ts theme={null}
z.record(z.string(), z.string()); // ✅
```
```ts theme={null}
z.record(z.string()); // Single argument allowed
```
### Improves enum support
Records with enum keys now ensure exhaustiveness:
```ts theme={null}
const myRecord = z.record(z.enum(["a", "b", "c"]), z.number());
// Zod 4: { a: number; b: number; c: number; }
// Zod 3: { a?: number; b?: number; c?: number; }
```
For optional keys, use `z.partialRecord()`:
```ts theme={null}
const myRecord = z.partialRecord(z.enum(["a", "b", "c"]), z.number());
// { a?: number; b?: number; c?: number; }
```
### `z.promise()` deprecated
If you have an input that may be a `Promise`, just `await` it before parsing with Zod.
### `z.literal()` drops `symbol` support
Symbols are no longer considered literal values.
### Static `.create()` factories dropped
Previously all Zod classes defined a static `.create()` method. These are now implemented as standalone factory functions.
```ts theme={null}
z.ZodString.create(); // ❌
z.string(); // ✅
```
### `z.intersection()` throws `Error` on merge conflict
When intersection results are unmergable, Zod now throws a regular `Error` instead of `ZodError`.
### Drops convenience methods
The undocumented convenience methods `z.ostring()`, `z.onumber()`, etc. have been removed.
## Internal Changes
### Updates generics
The generic structure of `ZodType` has changed:
```ts theme={null}
// Zod 3
class ZodType {
// ...
}
// Zod 4
class ZodType