Upgrade Zod v3 to v4

Quick Start

Migrate your entire src directory from Zod v3 to v4 with a single command:

schemashift migrate ./src -f zod-v3 -t v4

Preview changes first without modifying any files:

schemashift migrate ./src -f zod-v3 -t v4 --dry-run

Before & After

Side-by-side comparison of the most common Zod v3 patterns and their v4 equivalents. SchemaShift handles all of these automatically.

z.record() — explicit key type

// Implicit string key
const Config = z.record(z.number());

// Explicit key type required
const Config = z.record(z.string(), z.number());

.merge() → .extend()

const Full = Base.merge(Extra);

const Full = Base.extend(Extra.shape);

z.nativeEnum() → z.enum()

const Status = z.nativeEnum(MyEnum);

const Status = z.enum(MyEnum);

.superRefine() → .check()

schema.superRefine((val, ctx) => {
  ctx.addIssue({
    code: z.ZodIssueCode.custom,
    message: 'Invalid',
  });
});

schema.check((val, ctx) => {
  ctx.issues.push({
    code: z.ZodIssueCode.custom,
    message: 'Invalid',
  });
});

error.errors → error.issues

catch (err) {
  console.log(err.errors);
}

catch (err) {
  console.log(err.issues);
}

Error message params

z.string({
  invalid_type_error: 'Must be a string',
  required_error: 'Field is required',
});

z.string({
  error: 'Must be a string',
});

Full Conversion Reference

Every automatic transform that SchemaShift applies during the Zod v3 to v4 migration:

Edge Cases and Gotchas

These changes are not simple find-and-replace. They involve subtle behavioral shifts that can cause runtime bugs without any TypeScript errors:

• ZodError no longer extends Error — Any code using instanceof Error to catch Zod validation errors will silently stop matching. Switch to instanceof ZodError or check for error.issues.
• .transform() runs even when .refine() fails — In v3, .refine() before .transform() short-circuited on failure. In v4, the transform executes regardless, which may cause unexpected results or runtime errors if the transform assumes validated data.
• .default() + .optional() silent behavior change — In v3, z.string().default('hello').optional() returned undefined when no value was provided. In v4, the default value is applied even for optional fields. Review all combinations where .default() is chained with .optional().
• .catch() + .optional() behavior change — Similar to .default(), the interaction between .catch() and .optional() has changed in v4. Test all schemas using this combination.
• .pipe() is stricter — Zod v4 enforces stricter type compatibility within .pipe() chains. Workaround guidance is provided in TODO comments for schemas that need adjustment.
• .strict() and .passthrough() deprecated — Use z.strictObject() and z.looseObject() instead. The old methods still work but will be removed in a future release.
• Utility types moved to zod/v4/core — If you import ZodType, ZodSchema, ZodRawShape, or similar utility types, they now live in zod/v4/core instead of the main zod entrypoint.

Automated Migration with SchemaShift

Run a dry-run first to preview every change without modifying your codebase:

schemashift migrate ./src -f zod-v3 -t v4 --dry-run --verbose

Export a unified diff for code review before applying:

schemashift migrate ./src -f zod-v3 -t v4 --dry-run --output-diff v4-migration.patch

When you are ready, run the full migration with a backup:

schemashift migrate ./src -f zod-v3 -t v4

For large codebases, use canary mode to migrate a small percentage first:

schemashift migrate ./src -f zod-v3 -t v4 --canary 20

Migration Checklist

• Review all deprecation warnings (.strict(), .passthrough())
• Test all instanceof Error checks against ZodError
• Verify .default().optional() combinations behave as expected
• Check .transform() after .refine() chains for safety
• Review .catch().optional() combinations
• Update zod-validation-error to v5.0.0+
• Update drizzle-zod to a v4-compatible version
• Verify @trpc/server compatibility (v11 required for Zod v4)
• Update @hookform/resolvers if using react-hook-form
• Check zod-openapi / @asteasolutions/zod-to-openapi compatibility
• Regenerate zod-prisma / zod-prisma-types schemas if applicable
• Run your full test suite
• Run schemashift doctor to verify project health post-migration

Frequently Asked Questions

Related Guides

Ready to Upgrade?

Stop spending hours on manual find-and-replace. SchemaShift handles 20+ Zod v4 breaking changes automatically with full backup and rollback support.

npm install -g schemashift-cli

Get Individual License — $49 View All Plans