gatsbyjs/gatsby · error · Error

PageCreator: To query node "gatsbyPath" the "filePath" argum

Error message

PageCreator: To query node "gatsbyPath" the "filePath" argument must represent a file that exists.
Unable to find a file at: "${absolutePath}"

What it means

validatePathQuery's final rule: after all syntactic checks pass, the resolver attempts require.resolve against absolutePath (process.cwd()/src/pages + filePath) across every configured extension and an optional /index suffix. If none resolves to a real file, the filePath does not correspond to anything on disk and the build fails with the absolute path it tried. This is the catch-all for logically-correct-but-nonexistent routes.

Source

Thrown at packages/gatsby-plugin-page-creator/src/validate-path-query.ts:49

    )
  }

  const absolutePath = systemPath.join(process.cwd(), `src/pages`, filePath)

  const file = _.flatten(
    extensions.map(ext =>
      [``, `${systemPath.sep}index`].map(index => {
        try {
          return require.resolve(absolutePath + index + ext)
        } catch (e) {
          return false
        }
      })
    )
  ).filter(Boolean) as Array<string>

  if (file.length === 0 || file[0].length === 0) {
    throw new Error(
      `PageCreator: To query node "gatsbyPath" the "filePath" argument must represent a file that exists.
Unable to find a file at: "${absolutePath}"`
    )
  }
}

View on GitHub (pinned to 8b06340921)

Solutions

  1. Confirm a file exists at src/pages + filePath (the absolute path in the message) using ls.
  2. If the file uses an unsupported extension, register it in gatsby-config.js via gatsby-plugin-page-creator options.extensions.
  3. Re-run the build (gatsby clean && gatsby develop) to clear stale nodes if you recently added the file.
  4. Fix typos in the route path - it must match the on-disk directory/filename exactly (minus extension and trailing index).

Example fix

// before: page does not exist
gatsbyPath(filePath: "/about-us")
// src/pages/about.js exists but not about-us

// after: match an existing file
gatsbyPath(filePath: "/about")
Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs');
const path = require('path');
function resolvePageFile(filePath, extensions) {
  const abs = path.join(process.cwd(), 'src/pages', filePath);
  const found = extensions.flatMap(ext =>
    ['', '/index'].map(idx => {
      const candidate = abs + idx + ext;
      return fs.existsSync(candidate) ? candidate : null;
    })
  ).filter(Boolean);
  if (found.length === 0) {
    throw new Error(`No page file found for ${filePath} at ${abs}`);
  }
  return found[0];
}

Type guard

function pageFileExists(filePath, extensions) {
  const abs = path.join(process.cwd(), 'src/pages', filePath);
  return extensions.some(ext =>
    ['', '/index'].some(idx => fs.existsSync(abs + idx + ext))
  );
}

Prevention

When it happens

Trigger: Querying gatsbyPath for a filePath that points at a page that was never created: the file was deleted, renamed, not yet generated, or sits outside src/pages. Also fires when the extension of the file is not in the configured extensions list (e.g. a .vue file when gatsby is only configured for js/ts/mdx).

Common situations: Querying a route before creating the page; typos in the route segment; moving a file out of src/pages; using an extension gatsby-plugin-page-creator is not configured to pick up; race during incremental builds where the node is stale.

Related errors

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