vercel/next.js · error · Error

The provided export path '${pathname}' doesn't match the '${

Error message

The provided export path '${pathname}' doesn't match the '${page}' page.
Read more: https://nextjs.org/docs/messages/export-path-mismatch

What it means

Thrown by getParams() in the static-export pipeline when a candidate export pathname fails to match the page's compiled route regex. Next.js derives a regex from the page's dynamic route pattern (e.g. /blog/[slug]) and runs the supplied pathname through getRouteMatcher; a falsy result means the path cannot satisfy the route's parameter shape, so export is aborted. It guards against writing prerendered files to paths that the route could never actually serve.

Source

Thrown at packages/next/src/export/helpers/get-params.ts:32

 * Gets the params for the provided page.
 * @param page the page that contains dynamic path parameters
 * @param pathname the pathname to match
 * @returns the matches that were found, throws otherwise
 */
export function getParams(page: string, pathname: string) {
  // Because this is often called on the output of `getStaticPaths` or similar
  // where the `page` here doesn't change, this will "remember" the last page
  // it created the RegExp for. If it matches, it'll just re-use it.
  let matcher: RouteMatchFn
  if (last?.page === page) {
    matcher = last.matcher
  } else {
    matcher = getRouteMatcher(getRouteRegex(page))
  }

  const params = matcher(pathname)
  if (!params) {
    throw new Error(
      `The provided export path '${pathname}' doesn't match the '${page}' page.\nRead more: https://nextjs.org/docs/messages/export-path-mismatch`
    )
  }

  return params
}

View on GitHub (pinned to 0ae8c72462)

Solutions

Inspect the route file pattern and confirm every path returned by getStaticPaths (or set in exportPathMap) has the exact segment count and param positions the pattern requires.
Re-check trailing slash and base path settings (trailingSlash, basePath in next.config.js) since these change the pathname that getParams receives.
For optional catch-all routes, ensure paths omit (or fully provide) the optional segments consistently rather than mixing partial values.
Add a unit test that runs getStaticPaths output through the route matcher before deploying, to catch mismatches at CI time.

Example fix

// before: route file pages/post/[slug].js
export async function getStaticPaths() {
  return { paths: [{ params: { slug: 'a' } }, { params: {} }], fallback: false } // {} mismatches [slug]
}
// after
export async function getStaticPaths() {
  return { paths: [{ params: { slug: 'a' } }, { params: { slug: 'b' } }], fallback: false }
}

Defensive patterns

Strategy: validation

Validate before calling

import { getRouteMatcher } from 'next/dist/shared/lib/router/utils/route-matcher'
import { getRouteRegex } from 'next/dist/shared/lib/router/utils/route-regex'

function validateExportPaths(page: string, paths: string[]): string[] {
  const matcher = getRouteMatcher(getRouteRegex(page))
  const bad = paths.filter((p) => !matcher(p))
  if (bad.length) throw new Error(`Paths not matching ${page}: ${bad.join(', ')}`)
  return paths
}
// call inside getStaticPaths or a pre-export check

Type guard

function isValidExportPath(page: string, pathname: string): boolean {
  try {
    const { getRouteMatcher } = require('next/dist/shared/lib/router/utils/route-matcher')
    const { getRouteRegex } = require('next/dist/shared/lib/router/utils/route-regex')
    return Boolean(getRouteMatcher(getRouteRegex(page))(pathname))
  } catch {
    return false
  }
}

Try / catch

try {
  await nextBuild()
} catch (e) {
  if (e.message.includes("doesn't match the '")) {
    console.error('Export path mismatch — verify getStaticPaths vs route file')
  }
  throw e
}

Prevention

Keep getStaticPaths paths and the route filename in the same change/commit so they stay in sync.
Add a unit test that runs getStaticPaths output through the route matcher before deploying.
Avoid hand-editing exportPathMap for dynamic routes; derive paths from data.
Run `next build` locally before pushing — this error always surfaces at build time.

When it happens

Trigger: Occurs during `next build`/`next export` (or the export worker) for a dynamic route when getStaticPaths returns a path whose segments do not align with the route file, or an exportPathMap entry references a pathname that does not match the page's bracket-pattern. Also fires if a custom export path is hand-fed to getParams with the wrong segment count, optional catch-all mismatch, or trailing-slash difference.

Common situations: Typical during static export of a Pages Router dynamic route after editing getStaticPaths (returning paths like '/post' for a '/post/[slug]' page), or after renaming a route file without updating getStaticPaths. Also seen when exportPathMap is composed manually for a route whose pattern changed in a Next.js version upgrade, or when catch-all segments ([...slug]) are partially filled.

Related errors

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