What causes "Could not find matching component for page ${page.path}" in gatsbyjs/gatsby?

Verify the componentPath passed to createPage exists on disk and resolves correctly.

Could not find matching component for page ${page.path}

Error message

Could not find matching component for page ${page.path}

What it means

materializePageMode iterates all pages and looks up each page's component in store.getState().components by componentPath; if a page references a componentPath not present in the components map, it throws. The component must have been registered (compiled) before page-mode materialization.

Source

Thrown at packages/gatsby/src/utils/page-mode.ts:96

  return pageMode
}

/**
 * Persist page.mode for SSR/DSG pages to ensure they work with `gatsby serve`
 *
 * TODO: ideally IGatsbyPage["mode"] should not exist at all and instead we need a different entity
 *   holding this information: an entity that is only created in the end of the build e.g. Route
 *   then materializePageMode transforms to createRoutes
 */
export async function materializePageMode(): Promise<void> {
  const { pages, components } = store.getState()

  let dispatchCount = 0
  for (const page of pages.values()) {
    const component = components.get(page.componentPath)
    if (!component) {
      throw new Error(`Could not find matching component for page ${page.path}`)
    }
    const pageMode = resolvePageMode(page, component)

    // Do not materialize for SSG pages: saves some CPU time as `page.mode` === `SSG` by default when creating a page
    // and our pages are re-generated on each build, not persisted
    // (so no way to get DSG/SSR value from the previous build)
    if (pageMode !== `SSG`) {
      const action: IMaterializePageMode = {
        type: `MATERIALIZE_PAGE_MODE`,
        payload: { path: page.path, pageMode },
      }
      store.dispatch(action)
    }
    // Do not block task queue of the event loop for too long:
    if (dispatchCount++ % 100 === 0) {
      await new Promise(resolve => setImmediate(resolve))
    }
  }

View on GitHub (pinned to 8b06340921)

Solutions

Verify the componentPath passed to createPage exists on disk and resolves correctly.
Recreate pages after moving/renaming component files.
Ensure components are registered (standard createPage flow) before materializePageMode runs.

Example fix

// before: component moved but createPage still references old path
actions.createPage({ path: '/about', component: require.resolve('./src/templates/old-about.js') })
// after: point to the existing component
actions.createPage({ path: '/about', component: require.resolve('./src/templates/about.js') })

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs')
function componentFileExists(componentPath) {
  return fs.existsSync(componentPath)
}

Type guard

function componentRegistered(state, componentPath) { return state.components.has(componentPath) }

Prevention

Always require.resolve the component path so it is validated at build start.
Recreate pages whenever you move or rename template files.
Add a smoke test asserting every page's componentPath resolves.

When it happens

Trigger: A page created with a componentPath pointing to a missing/moved/non-existent component file, or a component that failed to register before materialization.

Common situations: Component file deleted or renamed after createPage; wrong/typo component path in createPage; custom createPage bypassing the component registration step; build ordering issue.

Related errors

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