Phased migration from Zod v3 to v4 in a monorepo: type mismatch with zodResolver (TS2769)

[tas-ricken]

Hello.

I'm working on a phased migration from zod v3 to v4 in a monorepo, but it isn't going well.
If you've completed a migration from zod v3 to v4, I'd appreciate it if you could share how you approached it.

We're trying to run zod v3 and v4 side by side via an alias, but we can't get @hookform/resolvers' zodResolver to accept a v4 instance, and we're stuck on the resulting error.
Specifically, zodResolver seems to behave as if it only accepts a zod v3 instance; when we pass a v4 schema, we get TS2769 (zod internal type version mismatch).

Below is our current project structure (the client is where the error remains unresolved).

• Monorepo root: zod v3 coexists with aliased zod v4
• core: existing schema module on zod v3.
• core-v2: schema module on zod v4. This layer redefines the schemas from core on top of v4. We provide schema builder functions so that the same schema can be generated (for the server) from different zod v4 instances.
• client: still depends on zod v3, with aliased zod v4 and zodResolver v5 added. Like core-v2, it directly references the root zod v4 schemas, but—likely due to the alias setup—passing a v4 schema to zodResolver triggers a type error (TS2769).
• server: depends directly on zod v4 within the module. For OpenAPI doc generation, schemas are defined via the core-v2 schema builder.

Directory structure

/example-project
|-- node_modules
|   |-- zod (v3.23.8)
|   └- zod-v4 (alias → [email protected])
|-- package.json            # workspaces: "packages/*"
└- packages
    |-- core                # Existing: zod v3 schemas
    |   |-- src/
    |   |   └- schemas.ts
    |   └- package.json    # dependencies: { "zod": "^3.23.8" } (uses node_modules in the monorepo root)
    |
    |-- core-v2             # New: zod v4 schemas (exports both builder and direct schemas)
    |   |-- src/
    |   |   └- schemas.ts
    |   └- package.json    # dependencies: { "zod-v4": "npm:zod@^4.1.12" } (uses node_modules in the monorepo root)
    |
    |-- client              # Vite + React
    |   |-- src/
    |   |   └- hooks/
    |   |       └- useUserForm.ts
    |   └- package.json
    |       # dependencies:
    |       #   "zod": "^3.23.8"
    |       #   "zod-v4": "npm:zod@^4.1.12",
    |       #   "react-hook-form": "^7.x"
    |       # devDependencies:
    |       #   "@hookform/resolvers": "^3.x",
    |       #   "hookform-resolvers-v5": "npm:@hookform/resolvers@^5.2.2"
    |
    └- server              # Hono + zod v4
        |-- src/
        |   └- routes/
        |       └- user.ts
        └- package.json    # dependencies: { "zod": "^4.1.12" }

Implementation examples

• Schema definition on the core-v2 (zod v4) side (both builder and direct export)

// core-v2/src/schemas.ts
import { z } from "zod-v4";

type zLocalType = typeof z;

export const createUserRequestSchemaBuilder = (zLocal: zLocalType) =>
  zLocal.object({
    name: zLocal.string().min(1).max(100),
    email: zLocal.string().email(),
    age: zLocal.number().int().positive().optional(),
  });

export const createUserRequestSchema = createUserRequestSchemaBuilder(z);

• Client-side hook (the builder is not used because the same z instance is shared)

// client/src/hooks/useUserForm.ts
import { zodResolver } from "hookform-resolvers-v5/zod";
import { createUserRequestSchema } from "core-v2/src/schemas";
import { useForm } from "react-hook-form";
import { z } from "zod-v4";

type CreateUserRequest = z.infer<typeof createUserRequestSchema>;

const formMethods = useForm<CreateUserRequest>({
  resolver: zodResolver(createUserRequestSchema), // 'No overload matches this call' error occurs here (see below)
  defaultValues: {
    name: "",
    email: "",
    age: undefined,
  },
});

• On the server module, generating schemas via the builder works fine

// server/src/schema/user.ts
import { z } from "@hono/zod-openapi";
import { userSchemaBuilder } from "core-v2/src/schemas";

/**
 * User schema (for Hono)
 */
const userSchemaForHono = userSchemaBuilder(z).openapi("User");

• However, TS2769 occurs in the client at zodResolver(createUserRequestSchema)

// client/src/hooks/useUserForm.ts
import { zodResolver } from "hookform-resolvers-v5/zod";
import { createUserRequestSchema } from "core-v2/src/schemas";
import { useState } from "react";
import { useForm } from "react-hook-form";
import { z } from "zod-v4";
type CreateUserRequest = z.infer<typeof createUserRequestSchema>;

const useUserForm = () => {
  const [submittedData, setSubmittedData] = useState<CreateUserRequest | null>(
    null
  );

  const formMethods = useForm<CreateUserRequest>({
    resolver: zodResolver(createUserRequestSchema),// The error below occurs
    defaultValues: {
      name: "",
      email: "",
      age: undefined,
    },
  });

client/src/hooks/useUserForm.ts(15,27): error TS2769: No overload matches this call.
Overload 1 of 4, '(schema: Zod3Type<...>): Resolver<...>', gave the following error.
Argument of type 'ZodObject<...>' is not assignable to parameter of type 'Zod3Type<...>'.
Types of property '\_def' are incompatible.
Property 'typeName' is missing in type '$ZodObjectDef<...>' but required in type '{ typeName: string; }'.
Overload 2 of 4, '(schema: $ZodType<...>): Resolver<...>', gave the following error.
The types of '\_zod.version.minor' are incompatible.
Type '1' is not assignable to type '0'.

• Notes
  • The error only reproduces when passing the aliased v4 schema to zodResolver(...) in the client
  • If we import the zod instance via a subpath as below and try to define a schema via the builder, we get a version mismatch error in zod.

import { zodResolver } from "hookform-resolvers-v5/zod";
import { createUserRequestSchemaBuilder } from "core-v2/src/schemas";
import { z } from "zod/v4";
type CreateUserRequest = z.infer<typeof createUserRequestSchema>;
const createUserRequestSchema = createUserRequestSchemaBuilder(z);
// Argument of type 'typeof import("example-project/node_modules/zod/v4/classic/external")' is not assignable to parameter of type 'typeof import("example-project/packages/core/node_modules/zod/v4/classic/external")'.
//   Type 'typeof import("example-project/node_modules/zod/v4/classic/external")' is missing the following properties from type 'typeof import("example-project/packages/core/node_modules/zod/v4/classic/external")': util, httpUrl, hostname, hex, and 14 more.

• We could avoid the error by redefining the schemas on the client and ignoring the ones in core, but that would be operationally painful; we'd prefer to keep the schemas shared.

import { zodResolver } from "hookform-resolvers-v5/zod";
import { useState } from "react";
import { useForm } from "react-hook-form";
import { z } from "zod/v4";

type CreateUserRequest = z.infer<typeof createUserRequestSchema>;
const createUserRequestSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  age: z.number().int().positive().optional(),
});

const useUserForm = () => {
  const [submittedData, setSubmittedData] = useState<CreateUserRequest | null>(
    null
  );

  const formMethods = useForm<CreateUserRequest>({
    resolver: zodResolver(createUserRequestSchema), // This avoids the error
    defaultValues: {
      name: "",
      email: "",
      age: undefined,
    },
  });

Information needed

• At this point the client-side zod migration is stuck as described above.
• If you have experience migrating zod versions, I'd appreciate advice on:
  • Common strategies for phased migration from zod v3 to v4 in a monorepo
  • Best practices for migrating to v4 while keeping v3 schemas around
  • Any architecture to resolve the issues described here

[dosubot[bot]]

Hi @tas-ricken! I'm Dosu and I’m helping the zod team.

I'm a bot trained on Zod's codebase and issues. Here’s what’s happening and how to move forward:

The TS2769 error with zodResolver and aliased Zod v4 schemas is a direct result of TypeScript seeing schemas from different Zod instances (even if they're both v4) as fundamentally incompatible. This happens because Zod’s internal types and branding are version- and instance-specific—TypeScript will not treat a schema from zod-v4 as assignable to a type from zod or vice versa, even if the runtime code is identical. This is enforced by Zod’s internal structure and there’s no built-in shim or workaround for cross-version compatibility in the codebase [source].

Best practices for phased migration in a monorepo:

• Use subpath imports: For Zod v3, import from zod/v3; for Zod v4, import from zod/v4/core (or zod/v4 for classic). Avoid aliases like zod-v4—they create multiple Zod instances and break type compatibility [source].
• Ensure all packages that need to share schemas use the same Zod version and instance. In a monorepo, this means using a single version in the root and referencing it via peerDependencies, not dependencies, in all subpackages [source].
• For incremental migration, keep both v3 and v4 schemas around, but never pass a schema from one version to a consumer expecting the other. Use builder functions that accept the local Zod instance to generate schemas in each consumer, so the schema is always created by the correct Zod version [source].
• Set your tsconfig.json to "moduleResolution": "node16" or "nodenext" to ensure subpath imports resolve correctly [source].
• Pin @hookform/resolvers to the same version everywhere, and make sure it matches the Zod version you’re using [source].

How to resolve your specific issue:

• In your client, make sure both @hookform/resolvers and your Zod import are using the same Zod instance. If you want to use Zod v4 with zodResolver, both must import from zod/v4 (not an alias, not the root, not a different node_modules path).
• If you need to share schemas, export builder functions from your schema packages that accept a Zod instance, and always call them with the local Zod import in the consumer. This ensures the schema is constructed by the right Zod version and instance [source].
• Avoid exporting raw schema objects across package boundaries if you have multiple Zod versions in play—export only inferred types or builder functions.
• If you see errors about incompatible Zod instances, check your lockfile and node_modules for duplicate Zod installations. Use peerDependencies and deduplicate.
• If you’re stuck, try deleting node_modules and your lockfile, then reinstalling after aligning all Zod and resolver versions [source].

References and further reading:

• Zod library author migration guide
• Zod v4 changelog and migration guide
• Relevant GitHub issue on type incompatibility
• Incremental migration discussion

If this answers your question, please close the issue. If you need more help, feel free to share a minimal reproduction!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[tas-ricken]

It seems that the issue can be resolved by using standardSchemaResolver instead of zodResolver in the resolver section of client/src/hooks/useUserForm.ts.

import { standardSchemaResolver } from "hookform-resolvers-v5/standard-schema";
...

const useUserForm = () => {
  const formMethods = useForm<CreateUserRequest>({
    resolver: standardSchemaResolver(createUserRequestSchema),
    defaultValues: {
      name: "",
      email: "",
      age: undefined,
    },
  });

References：
https://github.com/react-hook-form/resolvers/blob/master/standard-schema/src/standard-schema.ts
react-hook-form/resolvers#738