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

Error message

PageCreator: To query node "gatsbyPath" the "filePath" argument must be an absolute path, starting with a /
Please change this to: "/${filePath}"

What it means

validatePathQuery checks the `filePath` argument passed to the `gatsbyPath` field on Gatsby's Page node type. The first rule is that filePath must be absolute - it must begin with `/`. A relative path like `about` or `../about` is rejected because the resolver joins it against src/pages internally and a leading slash is the contract. The error message echoes the corrected form.

Source

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

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(

View on GitHub (pinned to 8b06340921)

Solutions

Prefix the filePath with `/`, e.g. gatsbyPath(filePath: "/about").
When building filePath dynamically, ensure the value starts with `/`: const p = path.startsWith('/') ? path : '/' + path.
Use the corrected value shown in the error message verbatim.

Example fix

// before
export const query = graphql`
  query {
    page(path: { eq: "about" }) {
      gatsbyPath(filePath: "about")
    }
  }
`

// after
export const query = graphql`
  query {
    pagePage {
      gatsbyPath(filePath: "/about")
    }
  }
`

Defensive patterns

Strategy: validation

Validate before calling

function ensureLeadingSlash(filePath) {
  if (typeof filePath !== 'string' || !filePath.startsWith('/')) {
    throw new Error(`filePath must start with '/': ${filePath}`);
  }
  return filePath;
}

Type guard

function isAbsolutePathLike(p) {
  return typeof p === 'string' && p.startsWith('/');
}

Prevention

Always write gatsbyPath filePath literals with a leading slash.
When interpolating, normalize: const fp = p.startsWith('/') ? p : '/' + p.

When it happens

Trigger: Querying `page.gatsbyPath(filePath: "about")` or any filePath without a leading slash in a GraphQL query, page component, or static query. Triggered during GraphQL validation/resolution of the gatsbyPath field.

Common situations: Copying a path from a url bar (no leading slash), constructing filePath dynamically without normalizing, or migrating from an older API that accepted relative paths.

Related errors

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