gatsbyjs/gatsby · error

Error: matchPath property is undefined for page ${page.path}

Error message

Error: matchPath property is undefined for page ${page.path}, should be a string

What it means

Thrown in Gatsby's requires-writer when building the match-path index: createMatchPathEntry receives a page whose matchPath is strictly undefined. The function's type promises matchPath: string, so an undefined value is treated as a programming error and the build panics. This is a defensive invariant guard, not a normal user-facing validation.

Source

Thrown at packages/gatsby/src/bootstrap/requires-writer.ts:88

 * code is based on @reach/router match utility (https://github.com/reach/router/blob/152aff2352bc62cefc932e1b536de9efde6b64a5/src/lib/utils.js#L224-L254)
 */
const getMatchPaths = (
  pages: Array<IGatsbyPage>
): Array<IGatsbyPageMatchPath> => {
  interface IMatchPathEntry extends IGatsbyPage {
    index: number
    score: number
    matchPath: string
  }

  const createMatchPathEntry = (
    page: IGatsbyPage,
    index: number
  ): IMatchPathEntry => {
    const { matchPath } = page

    if (matchPath === undefined) {
      return reporter.panic(
        `Error: matchPath property is undefined for page ${page.path}, should be a string`
      ) as never
    }

    return {
      ...page,
      matchPath,
      index,
      score: rankRoute(matchPath),
    }
  }

  const matchPathPages: Array<IMatchPathEntry> = []

  pages.forEach((page: IGatsbyPage, index: number): void => {
    if (page.matchPath && getPageMode(page) === `SSG`) {
      matchPathPages.push(createMatchPathEntry(page, index))
    }

View on GitHub (pinned to 8b06340921)

Solutions

1. Audit the code path that created the page: ensure matchPath is always assigned (use '' or null per the schema before this guard if a value is genuinely absent).
2. If you are a Gatsby contributor, normalize pages (default matchPath to a string) before they reach createMatchPathEntry.
3. Delete .cache and rebuild to rule out stale serialized page state from an older Gatsby version.

Example fix

// before
const entry = createMatchPathEntry({ ...page /* matchPath missing */ }, index)
// after
const entry = createMatchPathEntry({ ...page, matchPath: page.matchPath ?? `` }, index)

// Ensure pages passed to the match-path builder always carry matchPath
function isMatchPathPage(page): page is IMatchPathEntry['matchPath'] extends infer _ ? typeof page : never {
  return typeof page?.matchPath === 'string'
}
if (!isMatchPathPage(page)) page = { ...page, matchPath: '' }

When it happens

Trigger: A page object entered into the match-path index without a matchPath field (the field is undefined). The TS type is enforced at the boundary, so this fires when internal code bypasses typing or when a plugin/third-party directly mutates the page store.

Common situations: Gatsby major upgrade where the IGatsbyPage/matchPath contract changed; a custom plugin mutating store pages; corrupted .cache state.

Related errors

• page not found
• BabelPluginRemoveGraphQLQueries: the "${exportName}" export
• generateImageSource must be a function
• An error occurred building the slug parts. This is likely a
• Could not find matching operation for ${requestedPathOnDisk}

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/9d75d58e83a41075. Report an issue: GitHub.