getStaticPaths with "fallback: blocking" cannot be used with

Error message

getStaticPaths with "fallback: blocking" cannot be used with "output: export". See more info here: https://nextjs.org/advanced-features/static-html-export

What it means

Thrown in dev under output:'export' when a pages-router page's getStaticPaths returns fallback:'blocking'. Static HTML export cannot do blocking SSR fallback (there is no server at runtime to render on demand), so this combination is rejected. Detected when fallback === FallbackMode.BLOCKING_STATIC_RENDER.

Source

Thrown at packages/next/src/server/dev/next-dev-server.ts:906

            if (!prerenderedRoutes) {
              throw new Error(
                `Page "${page}" is missing exported function "generateStaticParams()", which is required with "output: export" config. See more info here: https://nextjs.org/docs/messages/generate-static-params`
              )
            }

            if (
              !prerenderedRoutes.some((item) => item.pathname === urlPathname)
            ) {
              throw new Error(
                `Page "${page}" is missing param "${pathname}" in "generateStaticParams()", which is required with "output: export" config.`
              )
            }
          }
        }

        if (!isAppPath && this.nextConfig.output === 'export') {
          if (fallback === FallbackMode.BLOCKING_STATIC_RENDER) {
            throw new Error(
              'getStaticPaths with "fallback: blocking" cannot be used with "output: export". See more info here: https://nextjs.org/docs/advanced-features/static-html-export'
            )
          } else if (fallback === FallbackMode.PRERENDER) {
            throw new Error(
              'getStaticPaths with "fallback: true" cannot be used with "output: export". See more info here: https://nextjs.org/docs/advanced-features/static-html-export'
            )
          }
        }

        const value: {
          staticPaths: string[] | undefined
          prerenderedRoutes: PrerenderedRoute[] | undefined
          fallbackMode: FallbackMode | undefined
        } = {
          staticPaths: prerenderedRoutes?.map((route) => route.pathname),
          prerenderedRoutes,
          fallbackMode: fallback,
        }

View on GitHub (pinned to 0ae8c72462)

Solutions

Change getStaticPaths to `fallback: false` and ensure paths covers all needed routes.
Pre-render every path explicitly in getStaticPaths.paths so no fallback is needed.
Remove output:'export' if blocking fallback SSR behavior is required.
Audit all getStaticPaths in the project for fallback:'blocking' once export is enabled.

Example fix

// before
export async function getStaticPaths() {
  return { paths: [{ params: { id: '1' } }], fallback: 'blocking' }
}

// after (static export compatible)
export async function getStaticPaths() {
  return { paths: [{ params: { id: '1' } }, { params: { id: '2' } }], fallback: false }
}

Defensive patterns

Strategy: validation

Validate before calling

// Forbid blocking fallback in pages-router under output:export
function checkGetStaticPathsForExport(paths: { fallback: string | boolean }) {
  if (paths.fallback === 'blocking') {
    throw new Error('getStaticPaths fallback:"blocking" is incompatible with output:"export"')
  }
}

Prevention

Before enabling output:'export', grep for fallback:'blocking' across getStaticPaths.
Use fallback:false and enumerate all paths for export.
Keep an export-mode CI build to catch fallback incompatibilities.

When it happens

Trigger: A pages-router page (isAppPath false) defines getStaticPaths with `fallback: 'blocking'` while next.config has output:'export'. The fallback check at line 905 throws.

Common situations: Enabling output:'export' on an existing project whose getStaticPaths uses blocking fallback. Copying a getStaticPaths pattern from a non-export app into an export project. Migrating to static export without auditing fallback usage.

Related errors

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