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

Error message

PageCreator: To query node "gatsbyPath" the "filePath" argument must omit the src/pages prefix.
Please change this to: "${filePath.replace(/\/?src\/pages\//, ``)}"

What it means

validatePathQuery's third rule: filePath must NOT include the `src/pages` prefix. Since gatsbyPath always resolves inside src/pages, including it again would double the prefix. The check uses filePath.includes(`src/pages`) so any occurrence (with or without slashes) trips it, and the message shows the prefix-stripped form.

Source

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

export function validatePathQuery(
  filePath: string,
  extensions: Array<string>
): void {
  // Paths must start with /
  if (filePath.startsWith(`/`) !== true) {
    throw new Error(`PageCreator: To query node "gatsbyPath" the "filePath" argument must be an absolute path, starting with a /
Please change this to: "/${filePath}"`)
  }

  // Paths must not include file extension
  if (/\.[a-z]+$/i.test(filePath)) {
    throw new Error(`PageCreator: To query node "gatsbyPath" the "filePath" argument must omit the file extension
Please change ${filePath} to "${filePath.replace(/\.[a-z]+$/i, ``)}"`)
  }

  // Paths must not utilize src/pages
  if (filePath.includes(`src/pages`)) {
    throw new Error(`PageCreator: To query node "gatsbyPath" the "filePath" argument must omit the src/pages prefix.
Please change this to: "${filePath.replace(/\/?src\/pages\//, ``)}"`)
  }

  // Paths must not include index
  if (/index$/.test(filePath)) {
    throw new Error(
      `PageCreator: To query node "gatsbyPath" the "filePath" argument must omit index.
Please change this to: "${filePath.replace(/index$/, ``)}"`
    )
  }

  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)

View on GitHub (pinned to 8b06340921)

Solutions

Remove the src/pages portion from filePath, e.g. use "/about" instead of "/src/pages/about".
If generating paths from __dirname or import.meta.url, strip everything up to and including src/pages.
Use the corrected value shown in the error message.

Example fix

// before
gatsbyPath(filePath: "/src/pages/about")

// after
gatsbyPath(filePath: "/about")

Defensive patterns

Strategy: validation

Validate before calling

function stripSrcPages(filePath) {
  if (filePath.includes('src/pages')) {
    return filePath.replace(/\/?src\/pages\//, '');
  }
  return filePath;
}

Type guard

function isBareRoute(p) {
  return typeof p === 'string' && !p.includes('src/pages');
}

Prevention

Use the route (the URL), not the project-relative file path, in gatsbyPath.
When deriving from __dirname, slice off everything through src/pages.

When it happens

Trigger: Passing gatsbyPath(filePath: "/src/pages/about") or "/src/pages/blog/post" - any filePath containing the literal `src/pages`.

Common situations: Copying the on-disk path straight from the editor or terminal; migrating queries after moving files into src/pages; auto-path generators that emit project-relative paths.

Related errors

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