gatsbyjs/gatsby · error

${pluginName} must set the absolute path to the page compone

Error message

${pluginName} must set the absolute path to the page component when creating a page

What it means

Thrown by createPage when validateComponent returns an error (component path issues) but the error does not set panicOnBuild, so report.panic is invoked. Covers cases where the component path is not absolute, points to a non-existent file, is empty, or has no default export. The returned string message is the user-facing fallback used in test env.

Source

Thrown at packages/gatsby/src/redux/actions/public.js:307

  const { error, panicOnBuild } = validateComponent({
    input: page,
    pluginName: name,
    errorIdMap: {
      noPath: `11322`,
      notAbsolute: `11326`,
      doesNotExist: `11325`,
      empty: `11327`,
      noDefaultExport: `11328`,
    },
  })

  if (error) {
    if (isNotTestEnv) {
      if (panicOnBuild) {
        report.panicOnBuild(error)
      } else {
        report.panic(error)
      }
    }
    return `${name} must set the absolute path to the page component when creating a page`
  }

  // check if we've processed this component path
  // before, before running the expensive "trueCasePath"
  // operation
  //
  // Skip during testing as the paths don't exist on disk.
  if (isNotTestEnv) {
    if (pageComponentCache.has(page.component)) {
      page.component = pageComponentCache.get(page.component)
    } else {
      const originalPageComponent = page.component
      const splitPath = splitComponentPath(page.component)

      // normalize component path

View on GitHub (pinned to 8b06340921)

Solutions

1. Use path.resolve to build an absolute component path.
2. Confirm the file exists on disk with the exact casing used in code.
3. Ensure the component file has a default export.
4. Check the specific validateComponent error code (11325-11328) printed for the precise failure.

Example fix

// before (relative path)
createPage({ path: `/p/`, component: `./src/templates/post.js` })
// after (absolute + default export)
createPage({ path: `/p/`, component: path.resolve(`./src/templates/post.js`) })
// src/templates/post.js
export default ({ data }) => <h1>{data.wpPost.title}</h1>

const path = require('path'), fs = require('fs')
const abs = path.isAbsolute(page.component) ? page.component : path.resolve(page.component)
if (!fs.existsSync(abs)) throw new Error(`Component not found: ${abs}`)
actions.createPage({ ...page, component: abs })

function isAbsoluteExistingComponent(p: string): boolean {
  return typeof p === 'string' && path.isAbsolute(p) && require('fs').existsSync(p)
}

When it happens

Trigger: page.component fails validateComponent: not absolute (11326), does not exist (11325), empty (11327), or no default export (11328); panicOnBuild is false so report.panic runs.

Common situations: Passing a relative path like `./src/templates/x.js`; a typo in the filename; a template file with no `export default`; case-sensitivity mismatch between macOS dev and Linux CI (trueCasePathSync reveals mismatches).

Related errors

• 11322
• 11323
• 11324
• ${pluginName} created a slice and didn't pass the path to th
• Pages can only be created by plugins. There wasn't a plugin

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