{"record":{"id":"b6e634ff751f4391","repo":"gatsbyjs/gatsby","slug":"could-not-read-match-paths-json-from-the-cache-di","errorCode":null,"errorMessage":"Could not read match-paths.json from the .cache directory","messagePattern":"Could not read match-paths\\.json from the \\.cache directory","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/gatsby/src/commands/serve.ts","lineNumber":55,"sourceCode":"interface IServeProgram extends IProgram {\n  prefixPaths: boolean\n}\n\nconst readMatchPaths = async (\n  program: IServeProgram\n): Promise<Array<IMatchPath>> => {\n  const filePath = path.join(program.directory, `.cache`, `match-paths.json`)\n  let rawJSON = `[]`\n  try {\n    rawJSON = await fs.readFile(filePath, `utf8`)\n  } catch (error) {\n    report.warn(error)\n    report.warn(\n      `Could not read ${chalk.bold(\n        `match-paths.json`\n      )} from the .cache directory`\n    )\n    report.warn(\n      `Client-side routing will not work correctly. Maybe you need to re-run ${chalk.bold(\n        `gatsby build`\n      )}?`\n    )\n  }\n  return JSON.parse(rawJSON) as Array<IMatchPath>\n}\n\nconst matchPathRouter =\n  (\n    matchPaths: Array<IMatchPath>,\n    options: {\n      root: string\n    }\n  ) =>\n  (\n    req: express.Request,\n    res: express.Response,","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/e85d62f1779e353eaac1753211629a26d123e26c/packages/gatsby/src/commands/serve.ts#L37-L73","documentation":"readMatchPaths, called when starting gatsby serve, fails to read .cache/match-paths.json (the file mapping client-side routes to HTML files). Without it the dev/preview server cannot route client-side paths to the right HTML output, so serving starts but client-side routing may 404; typically the site was never built or .cache was deleted.","triggerScenarios":"Thrown at packages/gatsby/src/commands/serve.ts:55 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Run `gatsby build` before `gatsby serve` so match-paths.json is regenerated","Do not delete the .cache directory between build and serve","Re-run build if the warning mentions needing to re-run `gatsby build`"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"e85d62f1779e353eaac1753211629a26d123e26c","analyzedAt":"2026-08-26T17:50:09.662Z","contentChangedAt":"2026-08-26T17:50:09.662Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}