Incompatible with Zod v4.4.x

Author: Wesley-YoungCreated May 1, 2026Updated Jul 25, 2026

Labelsbug

Description

After Zod is resolved to 4.4.1, a Nextra docs site that works with Zod 4.3.6 starts failing during both next build and next dev.

This happens even when the docs app itself does not directly depend on zod. In my workspace, [email protected] and [email protected] both depend on zod via ^4.1.12, so pnpm can resolve Nextra's Zod dependency to 4.4.1 when the lockfile is updated.

With Zod 4.3.6, the docs build succeeds. With Zod 4.4.1, next build fails during prerendering, and next dev fails to render the whole site with:

txt

Invalid input: expected nonoptional, received undefined

The browser-side stack in dev is only the React Server Components client stack:

txt

resolveErrorDev
../node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/react-server-dom-turbopack/cjs/react-server-dom-turbopack-client.browser.development.js (3260:51)

processFullStringRow
../node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/react-server-dom-turbopack/cjs/react-server-dom-turbopack-client.browser.development.js (4427:23)

processFullBinaryRow
../node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/react-server-dom-turbopack/cjs/react-server-dom-turbopack-client.browser.development.js (4370:7)

processBinaryChunk
../node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/react-server-dom-turbopack/cjs/react-server-dom-turbopack-client.browser.development.js (4593:19)

progress
../node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/react-server-dom-turbopack/cjs/react-server-dom-turbopack-client.browser.development.js (4924:9)

In production build, Next redacts the server component error:

txt

Error occurred prerendering page "/guide/communication".
[Error: An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details.] {
  digest: '...'
}
Export encountered an error on /[[...mdxPath]]/page: /guide/communication, exiting the build.

To reproduce:

Create or use a Nextra docs app with [email protected] and [email protected].
Ensure zod resolves to 4.3.6, build the site - succeeds.
Ensure zod resolves to 4.4.1, build again - fails while prerendering a normal MDX route.
Run dev command - the site fails to render with Invalid input: expected nonoptional, received undefined

Suspected Cause

Zod 4.4.0 includes stricter behavior around required object properties whose schema involves z.undefined(), plus related .catch(), .partial(), .default(), and .prefault() combinations.

From the Zod 4.4.0 release notes:

A property whose schema is z.undefined() is now treated as required. The key must be present, but its value may be undefined.

This seems likely related to Nextra's internal Zod schemas, especially the schemas used by nextra-theme-docs to validate layout/theme props and by nextra to validate head/config props.

For example, nextra-theme-docs/dist/layout.js validates layout props with:

javascript

const { data, error } = LayoutPropsSchema.safeParse(themeConfig);

if (error) {
  throw z.prettifyError(error);
}

and nextra-theme-docs/dist/schemas.js defines multiple strict object schemas with defaults and optional/defaulted React node fields, for example:

javascript

const feedbackSchema = z.strictObject({
  content: reactNode.default("Question? Give us feedback"),
  labels: z.string().default("feedback"),
  link: z.string().optional()
});

const nextThemesSchema = z.strictObject({
  attribute: z.union([attributeSchema, z.array(attributeSchema)]).default("class"),
  defaultTheme: z.string().default("system"),
  disableTransitionOnChange: z.boolean().default(true),
  forcedTheme: z.string().optional(),
  storageKey: z.string().default("theme")
});

const themeSwitchSchema = z.strictObject({
  dark: z.string().default("Dark"),
  light: z.string().default("Light"),
  system: z.string().default("System")
});

const LayoutPropsSchema = z.strictObject({
  // ...
  feedback: feedbackSchema.default(feedbackSchema.parse({})),
  nextThemes: nextThemesSchema.default(nextThemesSchema.parse({})),
  themeSwitch: themeSwitchSchema.default(themeSwitchSchema.parse({})),
  // ...
});

I have not confirmed the exact field that triggers expected nonoptional, received undefined, but the failure appears to come from Nextra's own Zod-based validation path rather than from userland docs code.

Suggested Fix

Possible fixes might include one of the following:

Update Nextra's internal Zod schemas so they are compatible with Zod 4.4.x.
Add regression coverage for Zod 4.4.x.
If Nextra is not yet compatible with Zod 4.4.x, narrow the dependency range from ^4.1.12 to avoid installing 4.4.x.

Source: shuding/nextra

View original on GitHub View discussion on GitHub