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

Error message

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

What it means

validatePathQuery's second rule: filePath must NOT include a file extension. The regex /\.[a-z]+$/i matches a trailing extension like `.js`, `.tsx`, `.md`. Because gatsbyPath resolves against src/pages across all supported extensions (js, jsx, ts, tsx, md, mdx...), the caller must give the logical route, not the filename. The message shows the extension-stripped form to use.

Source

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

import _ from "lodash"
import systemPath from "path"

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)

View on GitHub (pinned to 8b06340921)

Solutions

Drop the trailing extension from filePath, e.g. use "/about" instead of "/about.js".
Strip it programmatically if generated: filePath.replace(/\.[a-z]+$/i, '').
Use the value suggested in the error message.

Example fix

// before
gatsbyPath(filePath: "/about.tsx")

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

Defensive patterns

Strategy: validation

Validate before calling

function stripExtension(filePath) {
  if (/\.[a-z]+$/i.test(filePath)) {
    return filePath.replace(/\.[a-z]+$/i, '');
  }
  return filePath;
}

Type guard

function isExtensionless(p) {
  return typeof p === 'string' && !/\.[a-z]+$/i.test(p);
}

Prevention

Copy route paths, not file names, into gatsbyPath queries.
Add an eslint rule or pre-commit grep that flags gatsbyPath filePath literals containing extensions.

When it happens

Trigger: Passing gatsbyPath(filePath: "/about.js") or "/blog/post.mdx" - any filePath ending in a dot followed by letters.

Common situations: Copy-pasting the actual filename from src/pages into the query; tooling that auto-completes file paths; refactoring that leaves an old extension in the query.

Related errors

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