Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readReact
#React#react-hook-form#Zod#TypeScript
A form panel splitting into input and output plates with a cyan resolver bridge, amber mismatch stud

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:

code
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:

ts
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 needed

When the schema really does have an input and an output shape, supply all three generics:

ts
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:

bash
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
ts
// 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 here

The version matrix that makes this error appear or disappear:

bash
# 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"
ts
// 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 mentionsReal causeFix
Resolver<...> not assignable, parse missingresolvers v4 or older against zod 4upgrade to @hookform/resolvers@^5
useForm<...> generic complaintexplicit generic blocking inferenceremove the generic
unknown where number expectedz.coerce input vs outputthree generics, or valueAsNumber
two zod@ entries in npm lsduplicate schema librarydedupe so one zod is installed
works in .tsx, fails in .tsdifferent strict settings per projectalign tsconfig
Schema featureInput typeOutput typeType annotation needed
z.string()stringstringnone
z.number().default(0)`numberundefined`number
z.coerce.number()unknownnumberthree generics
z.string().transform(Number)stringnumberthree generics
z.preprocess(...)unknowninner typethree 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:

ts
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:

tsx
<input type="number" {...register("slots", { valueAsNumber: true })} />
ts
const schema = z.object({ slots: z.number().int().min(1) }); // no coerce const form = useForm({ resolver: zodResolver(schema) }); // no generics

valueAsNumber 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:

ts
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:

bash
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.

ts
// 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 editor

6. 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:

ts
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/resolvers v3 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.infer as the field-values generic on a schema with coercion. z.infer is the output shape.
  • Adding three generics to every form. Plain schemas need none, and the extra annotation can hide a mismatch.
  • Ignoring a duplicate zod in npm 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 defaultValues typing with the three-generic form. A default of the wrong shape now fails at the useForm call.

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 documentation

The React documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit React work — they run entirely in this browser tab, so nothing you paste leaves your device.

All React guides

More in React

All React guides

The guides filed next to this one in React, in library order.