vercel/next.js · error · Error

Invalid fallback option: ${fallbackField}. Fallback option m

Error message

Invalid fallback option: ${fallbackField}. Fallback option must be a string, null, undefined, or false.

What it means

Thrown by parseFallbackField() when the fallback field from the prerender manifest is not one of the allowed types: string, null, undefined, or false. Any other value (notably boolean true, a number, or an object) is rejected because the FallbackMode enum cannot represent it. This indicates the manifest was written incorrectly, typically by a malformed getStaticPaths fallback.

Source

Thrown at packages/next/src/lib/fallback.ts:49

/**
 * Parses the fallback field from the prerender manifest.
 *
 * @param fallbackField The fallback field from the prerender manifest.
 * @returns The fallback mode.
 */
export function parseFallbackField(
  fallbackField: string | boolean | null | undefined
): FallbackMode | undefined {
  if (typeof fallbackField === 'string') {
    return FallbackMode.PRERENDER
  } else if (fallbackField === null) {
    return FallbackMode.BLOCKING_STATIC_RENDER
  } else if (fallbackField === false) {
    return FallbackMode.NOT_FOUND
  } else if (fallbackField === undefined) {
    return undefined
  } else {
    throw new Error(
      `Invalid fallback option: ${fallbackField}. Fallback option must be a string, null, undefined, or false.`
    )
  }
}

export function fallbackModeToFallbackField(
  fallback: FallbackMode,
  page: string | undefined
): string | false | null {
  switch (fallback) {
    case FallbackMode.BLOCKING_STATIC_RENDER:
      return null
    case FallbackMode.NOT_FOUND:
      return false
    case FallbackMode.PRERENDER:
      if (!page) {
        throw new Error(
          `Invariant: expected a page to be provided when fallback mode is "${fallback}"`

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Delete the .next directory and rebuild so the prerender manifest is regenerated correctly.
2. Audit any custom cache handler or build plugin that mutates the prerender manifest's fallback field.
3. Confirm getStaticPaths returns a supported fallback value: true, 'blocking', or false (the framework normalizes these).
4. Verify Next.js version consistency across build and runtime (a stale .next from a different version can carry the wrong shape).

Example fix

// before — manual manifest edit produced fallback: 1
// .next/prerender-manifest.json
{ "routes": { "/[slug]": { "fallback": 1 } } }
// after — delete stale build and rebuild
// rm -rf .next && pnpm build

function isValidFallback(v: unknown): v is string | null | undefined | false {
  return v === null || v === undefined || v === false || typeof v === 'string'
}
// validate the manifest before relying on it
if (!isValidFallback(manifest.routes['/[slug]'].fallback)) {
  throw new Error('prerender manifest has invalid fallback field')
}

function isValidFallback(v: unknown): v is string | null | undefined | false {
  return v === null || v === undefined || v === false || typeof v === 'string'
}

When it happens

Trigger: Triggered when reading the prerender manifest's fallback field for a dynamic Pages Router route during request handling. A corrupted manifest or a getStaticPaths returning an unsupported fallback value lands here. The field is expected to be the string page path (PRERENDER), null (blocking), false (not-found), or undefined.

Common situations: Manually editing the prerender manifest; a custom cache handler that rewrites the manifest incorrectly; an old Next.js manifest format loaded by a newer Next.js version; or a getStaticPaths returning fallback: true in a code path that bypassed parseStaticPathsResult normalization.

Related errors

• The provided export path '${pathname}' doesn't match the '${
• Manifest file is empty
• Command failed: ${command} ${args.join(' ')} (exit ${code})
• Missing ${NEXT_BIN}. Build Next.js first (pnpm --filter=next
• Command failed: ${command} ${args.join(' ')} (exit ${code})

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/846f31a0e2b313b6. Report an issue: GitHub.