gatsbyjs/gatsby · error

Could not read match-paths.json from the .cache directory

Error message

Could not read match-paths.json from the .cache directory

What it means

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.

Source

Thrown at packages/gatsby/src/commands/serve.ts:55

interface IServeProgram extends IProgram {
  prefixPaths: boolean
}

const readMatchPaths = async (
  program: IServeProgram
): Promise<Array<IMatchPath>> => {
  const filePath = path.join(program.directory, `.cache`, `match-paths.json`)
  let rawJSON = `[]`
  try {
    rawJSON = await fs.readFile(filePath, `utf8`)
  } catch (error) {
    report.warn(error)
    report.warn(
      `Could not read ${chalk.bold(
        `match-paths.json`
      )} from the .cache directory`
    )
    report.warn(
      `Client-side routing will not work correctly. Maybe you need to re-run ${chalk.bold(
        `gatsby build`
      )}?`
    )
  }
  return JSON.parse(rawJSON) as Array<IMatchPath>
}

const matchPathRouter =
  (
    matchPaths: Array<IMatchPath>,
    options: {
      root: string
    }
  ) =>
  (
    req: express.Request,
    res: express.Response,

View on GitHub (pinned to e85d62f177)

Solutions

1. Run `gatsby build` before `gatsby serve` so match-paths.json is regenerated
2. Do not delete the .cache directory between build and serve
3. Re-run build if the warning mentions needing to re-run `gatsby build`

When it happens

Trigger: Thrown at packages/gatsby/src/commands/serve.ts:55 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gatsbyjs/gatsby@e85d62f177 (2026-08-26). Data as JSON: /api/errors/b6e634ff751f4391. Report an issue: GitHub.