Zod 4 support for `@tanstack/zod-adapter` (specifically `fallback`)

[ptts]

Update 2025-07-16:
Nice! With the newest update from zod a new zod update coming out (hopefully) soon, fallback is not will not be necessary anymore! 🎊 (More infos)

---

Discussion: #4092

Which project does this relate to?

Router (@tanstack/zod-adapter)

Describe the bug

It appears that fallback from @tanstack/zod-adapter isn't ready for Zod v4.
More information about the expected behavior is in my comment below: #4322 (comment)

Steps to Reproduce the Bug or Issue

import { z } from "zod/v4";
import { fallback, zodValidator } from "@tanstack/zod-adapter";

const searchParamSchema = z.object({
  test: fallback(z.string().optional(), null).default(null),
//               ^ ❗ Type Error at z.string().optional()
});

Type Error:

Argument of type 'ZodOptional<ZodString>' is not assignable to parameter of type 'ZodTypeAny'.
  Type 'ZodOptional<ZodString>' is missing the following properties from type 'ZodType<any, any, any>': _type, _parse, _getType, _getOrReturnCtx, and 7 more.ts(2345)

Expected behavior

Zod 4 support

[carlbleick]

I have not tested it yet but both zod and tanstack router support standard schema, so I would assume it just works?
The docs say arktype doesn't need an adapter because it supports standard schema… Might be wrong tho

[scotttrinh]

Yeah just tested this and it does appear that Zod v4 works via the Standard Schema support.

[ptts]

I am talking about a more specific use-case.

Generally, Zod 4 search param validation works fine, both via zodValidator and also if just passed in without an adapter (through standard schema):

i.e., this works fine:

import { createFileRoute } from "@tanstack/react-router";
import { z } from "zod/v4"; // <-

export const Route = createFileRoute("/test")({
  validateSearch: z.object({
    sort: z.enum(["newest", "oldest", "price"]).catch("newest"),
  }), // ✅ no type error
});

But, currently, I can do this:

import { createFileRoute } from "@tanstack/react-router";
import { fallback, zodValidator } from "@tanstack/zod-adapter";
import { z } from "zod";

const searchSchema = z.object({
  sort: fallback(z.enum(["newest", "oldest", "price"]), "newest"),
});

export const Route = createFileRoute("/test")({
  validateSearch: zodValidator(searchSchema),
});

Now, when I link to that page via <Link to="/test" />:

• search parameter must be passed ✅
• search.filter must be one of the 3 defined values ✅
• when someone navigates to that page with an invalid param, it gracefully falls back to "newest" (no error) ✅

I want to replicate this behavior with Zod 4:

import { createFileRoute } from "@tanstack/react-router";
import { fallback, zodValidator } from "@tanstack/zod-adapter";
import { z } from "zod/v4";

const searchSchema = z.object({
  sort: z.enum(["newest", "oldest", "price"]).catch("newest"),
});

export const Route = createFileRoute("/test-route")({
  validateSearch: searchSchema, // via Standard Schema support
});

But now, when I link to this route:

  <Link to="/test" search={{ sort: "does_not_exist" }} /> // NO Type Error ❌

Expected behavior:

• search parameter must be passed ✅
• ➡️ search.filter must be one of the 3 defined values ❌ (It's now typed as "newest" | "oldest" | "price" | Whatever.) (Not sure where Whatever comes from, if that's from zod, standard schema or Tanstack Router Whatever comes from zod)
• when someone navigates to that page with an invalid param, it gracefully falls back to "newest" (no error) ✅

I do not get a type error for invalid values. This is what fallback used to solve, but fallback gives a type error when used with Zod 4.

Same behavior if I do the same thing with zodValidator but without fallback;

import { createFileRoute } from "@tanstack/react-router";
import { zodValidator } from "@tanstack/zod-adapter";
import { z } from "zod/v4";

const searchSchema = z.object({
  // sort: fallback(z.enum(["newest", "oldest", "price"], "price"), "newest"), // cannot use fallback without a type error (see original post)
  sort: z.enum(["newest", "oldest", "price"]).catch("newest"),
});

export const Route = createFileRoute("/test")({
  validateSearch: zodValidator(searchSchema),
});

[ptts]

Update 2: My bad, I guess it takes a bit longer as it's still in Canary and should ship in zod 4.1.0

Update:
Nice! With the newest update from zod, fallback is not necessary anymore! 🎊

More infos here:
#4442 (comment)

tl;dr:
Just update to the most recent version of zod and use the schema directly with .catch() without the adapter.

export const Route = createFileRoute("/test")({
  validateSearch: z.object({
    sort: z.enum(["newest", "oldest", "price"]).catch("newest"),
  }),
});

This just works now ✨: Typescript requires you to always pass a value for sort and at runtime invalid values gracefully fall back to newest.

[niba]

Just to clarify, the fix is already in ⁠canary and should ship with zod 4.1.0 (or 4.0.6).
Have you installed ⁠canary version of zod @ptts, or is there some magic I’m missing? 😄

[ptts]

Just to clarify, the fix is already in ⁠canary and should ship with zod 4.1.0 (or 4.0.6). Have you installed ⁠canary version of zod @ptts, or is there some magic I’m missing? 😄

Oh man, I guess you're right... I was only testing the regular z.infer<typeof schema> and didn't consider that StandardSchemaV1.InferInput<typeof schema> returns a different type which still contains Whatever in 4.0.5 😔 Well, soon though! Sorry everyone if you also already eagerly refactored your codebase 😄