{"record":{"id":"38ef13280c27ef71","repo":"gatsbyjs/gatsby","slug":"could-not-find-matching-component-for-page-page","errorCode":null,"errorMessage":"Could not find matching component for page ${page.path}","messagePattern":"Could not find matching component for page (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/gatsby/src/utils/page-mode.ts","lineNumber":96,"sourceCode":"\n  return pageMode\n}\n\n/**\n * Persist page.mode for SSR/DSG pages to ensure they work with `gatsby serve`\n *\n * TODO: ideally IGatsbyPage[\"mode\"] should not exist at all and instead we need a different entity\n *   holding this information: an entity that is only created in the end of the build e.g. Route\n *   then materializePageMode transforms to createRoutes\n */\nexport async function materializePageMode(): Promise<void> {\n  const { pages, components } = store.getState()\n\n  let dispatchCount = 0\n  for (const page of pages.values()) {\n    const component = components.get(page.componentPath)\n    if (!component) {\n      throw new Error(`Could not find matching component for page ${page.path}`)\n    }\n    const pageMode = resolvePageMode(page, component)\n\n    // Do not materialize for SSG pages: saves some CPU time as `page.mode` === `SSG` by default when creating a page\n    // and our pages are re-generated on each build, not persisted\n    // (so no way to get DSG/SSR value from the previous build)\n    if (pageMode !== `SSG`) {\n      const action: IMaterializePageMode = {\n        type: `MATERIALIZE_PAGE_MODE`,\n        payload: { path: page.path, pageMode },\n      }\n      store.dispatch(action)\n    }\n    // Do not block task queue of the event loop for too long:\n    if (dispatchCount++ % 100 === 0) {\n      await new Promise(resolve => setImmediate(resolve))\n    }\n  }","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/utils/page-mode.ts#L78-L114","documentation":"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.","triggerScenarios":"A page created with a componentPath pointing to a missing/moved/non-existent component file, or a component that failed to register before materialization.","commonSituations":"Component file deleted or renamed after createPage; wrong/typo component path in createPage; custom createPage bypassing the component registration step; build ordering issue.","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."],"exampleFix":"// before: component moved but createPage still references old path\nactions.createPage({ path: '/about', component: require.resolve('./src/templates/old-about.js') })\n// after: point to the existing component\nactions.createPage({ path: '/about', component: require.resolve('./src/templates/about.js') })","handlingStrategy":"validation","validationCode":"const fs = require('fs')\nfunction componentFileExists(componentPath) {\n  return fs.existsSync(componentPath)\n}","typeGuard":"function componentRegistered(state, componentPath) { return state.components.has(componentPath) }","tryCatchPattern":null,"preventionTips":["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."],"tags":["pages","components","build"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}