react-hook-form with zod 4: resolver type errors after the upgrade
Zod 4 split input from output and resolvers v5 re-typed Resolver. Drop the generic, or pass all three, and the errors disappear.

Introduction & Quick Summary
Symptom. A form that has worked for a year fails tsc --noEmit right after a dependency bump, with the error pointing at the resolver rather than at any field:
Type 'Resolver<{ title: string; slots: unknown }, any, { title: string; slots: number }>'
is not assignable to type 'Resolver<{ title: string; slots: number }, any,
{ title: string; slots: number }>'.
Types of parameters 'values' and 'values' are incompatible.
Type '{ title: string; slots: number }' is not assignable to type
'{ title: string; slots: unknown }'.Nothing about the form changed. npm run dev works, validation works at runtime, and the page renders. Only the types broke, which is why this tends to surface on a Friday build.
Cause. Two type changes landed together. Zod 4 gave schemas separate input and output types, because z.coerce, preprocess and transform accept one shape and produce another. @hookform/resolvers v5 then re-typed Resolver with three generics: field values, context, and transformed values. An explicit useForm<FormValues> supplies only the first generic, so TypeScript stops inferring the other two and compares your annotation with a resolver that has a different input side.
Fix. Stop annotating the form and let the resolver own the typing:
const schema = z.object({
title: z.string().min(1),
slots: z.number().int().min(1),
});
const form = useForm({ resolver: zodResolver(schema) });
// form values are inferred; no generic neededWhen the schema really does have an input and an output shape, supply all three generics:
const schema = z.object({ slots: z.coerce.number().int().min(1) });
const form = useForm<z.input<typeof schema>, unknown, z.output<typeof schema>>({
resolver: zodResolver(schema),
});That is the whole fix for most codebases. What follows explains which of the three causes you are looking at, and how to keep the version matrix from drifting back.
Core Mechanics, Signatures & Reproducible Setup
zodResolver(schema) returns a Resolver<Input, Context, Output>. useForm is declared as UseFormProps<TFieldValues, TContext, TTransformedValues>, and its resolver property is Resolver<TFieldValues, TContext, TTransformedValues>. Inference works only when all three are left to be inferred; an explicit first generic turns inference off for the rest, and the default for TTransformedValues becomes TFieldValues.
Reproduce the failure with five files and no application code:
npm create vite@latest rhf-demo -- --template react-ts
cd rhf-demo && npm install react-hook-form zod @hookform/resolvers
npm ls zod @hookform/resolvers react-hook-form// src/broken.ts
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
const schema = z.object({ slots: z.coerce.number().int().min(1) });
type FormValues = z.infer<typeof schema>; // number
export const useFormBroken = () =>
useForm<FormValues>({ resolver: zodResolver(schema) }); // TS2345 hereThe version matrix that makes this error appear or disappear:
# compatible set for zod 4
npm install react-hook-form@^7.55 @hookform/resolvers@^5 zod@^4
# a second zod 3 copy under any dependency re-creates the mismatch
npm ls zod --all | grep -c "zod@3"// the three-generic form, when input and output genuinely differ
useForm<z.input<typeof schema>, unknown, z.output<typeof schema>>({
resolver: zodResolver(schema),
defaultValues: { slots: 1 },
});Note unknown for the context generic: it is the honest value when no context is passed to handleSubmit, and it is what the resolver will infer anyway.
Key Comparison Table
| Error text mentions | Real cause | Fix |
|---|---|---|
Resolver<...> not assignable, parse missing | resolvers v4 or older against zod 4 | upgrade to @hookform/resolvers@^5 |
useForm<...> generic complaint | explicit generic blocking inference | remove the generic |
unknown where number expected | z.coerce input vs output | three generics, or valueAsNumber |
two zod@ entries in npm ls | duplicate schema library | dedupe so one zod is installed |
works in .tsx, fails in .ts | different strict settings per project | align tsconfig |
| Schema feature | Input type | Output type | Type annotation needed |
|---|---|---|---|
z.string() | string | string | none |
z.number().default(0) | `number | undefined` | number |
z.coerce.number() | unknown | number | three generics |
z.string().transform(Number) | string | number | three generics |
z.preprocess(...) | unknown | inner type | three generics |
z.object({ a: z.string() }).optional() | `{...} | undefined` | {...} |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. A helper hook that wraps useForm
Generic wrappers are where the explicit annotation gets reintroduced by accident. The version below keeps inference intact by deriving both shapes from the schema type instead of from z.infer:
import { useForm, type UseFormProps, type FieldValues } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import type { z } from "zod";
export function useZodForm<S extends z.ZodType>(
schema: S,
options?: Omit<UseFormProps<z.input<S>, unknown, z.output<S>>, "resolver">,
) {
return useForm<z.input<S>, unknown, z.output<S>>({
resolver: zodResolver(schema),
...options,
});
}The mistake to avoid is useForm<z.infer<S>>(...): z.infer is the output type, and using it as the field-values generic is exactly the mismatch the compiler is reporting.
2. Coercion at the field instead of in the schema
When a numeric field arrives from a text input, there are two valid designs, and mixing them produces the unknown complaint. The first keeps coercion in the schema and annotates three generics. The second keeps the schema strict and coerces at registration:
<input type="number" {...register("slots", { valueAsNumber: true })} />const schema = z.object({ slots: z.number().int().min(1) }); // no coerce
const form = useForm({ resolver: zodResolver(schema) }); // no genericsvalueAsNumber gives NaN for an empty field, which zod rejects with a message you can control; that is usually better than the unknown input type spreading through the component.
3. Defaults that change the input shape
defaultValues is typed against the field values, so a default of undefined forces optionality on the input side. A schema with a default and a form with a different default disagree in a way TypeScript reports at the resolver:
const schema = z.object({ slots: z.number().default(1) }); // input: number | undefined
const form = useForm<z.input<typeof schema>, unknown, z.output<typeof schema>>({
resolver: zodResolver(schema),
defaultValues: { slots: 1 },
});If you would rather not carry three generics, drop .default() from the schema and put the default in defaultValues only. One source of truth for the initial value keeps the two sides identical.
4. Two zod copies in one tree
npm ls zod showing both zod@4 and a nested zod@3 explains a resolver that fails only in files importing the nested copy, usually inside a UI library:
npm ls zod
npm dedupe
# or pin one version with an override{
"overrides": {
"zod": "^4.0.0"
}
}Overrides are blunt, so check whether the dependent package truly supports zod 4 before forcing it. When it does not, the alternative is to keep that boundary on zod 3 and avoid sharing schemas across it.
5. Reading the error in the direction it is written
The message reads "type A is not assignable to type B"; A is what your resolver produces, B is what useForm expects from your annotation. Looking at the two object types side by side, the differing field is the field with a transform, a default or a coercion. That is a faster diagnosis than reading the whole generic chain.
// print both shapes while debugging
type In = z.input<typeof schema>;
type Out = z.output<typeof schema>;
const debug: [In, Out] = null as never; // hover both in the editor6. Runtime vs types: what actually gets submitted
handleSubmit receives the transformed values, so the output type is what your submit handler sees, even when the form fields are typed as the input:
const onSubmit = (values: z.output<typeof schema>) => {
// slots is a number here, even if the input element held a string
};
<form onSubmit={form.handleSubmit(onSubmit)}>This is worth writing down in the component: the three-generic form is not a workaround for a type bug, it describes a real difference between what the DOM holds and what the API receives.
Common Compilation/Runtime Mistakes & Version Gotchas
- Upgrading zod 4 while keeping
@hookform/resolversv3 or v4. The resolver types are built against a different schema surface. - Keeping
useForm<FormValues>. It disables inference for the context and transformed-values generics. - Using
z.inferas the field-values generic on a schema with coercion.z.inferis the output shape. - Adding three generics to every form. Plain schemas need none, and the extra annotation can hide a mismatch.
- Ignoring a duplicate
zodinnpm ls. The error moves to whichever file imports the older copy. - Casting
as Resolver<...>. It silences the compiler and leaves the runtime shape unchanged. - Assuming a type error means validation is broken. It usually is not, so a code change to the schema can break working validation.
- Forgetting
defaultValuestyping with the three-generic form. A default of the wrong shape now fails at theuseFormcall.
If the schema is generated from JSON or an OpenAPI document, run it through the JSON formatter first; and when the types are agreed but the validation messages are not, check the patterns with the regex tester rather than reading rendered errors.
Reference: useForm API, the @hookform/resolvers v5 release notes, and the zod 4 changelog on the coercion input type change.
Official references
primary documentationThe React documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit React work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related React guides
All React guidesReact: An update inside a test was not wrapped in act(...)
The warning means a state update escaped the test's act scope. Await the interaction, use findBy queries, and wrap manual updates properly.
React: Cannot update a component while rendering a different component
The warning means one component scheduled state for another during render. Derive the value or move the write to a handler.
React Compiler: Cannot reassign variable after render completes
The immutability rule flags a closure that writes a render-scoped value. Decide whether it is a real bug, a false positive, or a bailout.
React: Too many re-renders. React limits the number of renders
A setter runs during render and schedules another render. Fix the invoked handler, the unstable dependency, or the prop-to-state copy.
More in React
All React guidesThe guides filed next to this one in React, in library order.