gatsbyjs/gatsby · error

${filePath} should be an absolute path.

Error message

${filePath} should be an absolute path.

What it means

convertPathsToAbsolute enforces path.isAbsolute on job inputPaths before hashing/scheduling, because the worker pool uses exact path strings for dedup and content hashing. A relative path is rejected outright.

Source

Thrown at packages/gatsby/src/utils/jobs/manager.ts:47

let activeJobs = 0
let isListeningForMessages = false
let hasShownIPCDisabledWarning = false

const jobsInProcess: Map<
  string,
  { id: string; deferred: pDefer.DeferredPromise<Record<string, unknown>> }
> = new Map()
const externalJobsMap: Map<
  string,
  { job: InternalJob; deferred: pDefer.DeferredPromise<any> }
> = new Map()

/**
 * We want to use absolute paths to make sure they are on the filesystem
 */
function convertPathsToAbsolute(filePath: string): string {
  if (!path.isAbsolute(filePath)) {
    throw new Error(`${filePath} should be an absolute path.`)
  }

  return slash(filePath)
}
/**
 * Get contenthash of a file
 */
function createFileHash(path: string): string {
  return hasha.fromFileSync(path, { algorithm: `sha1` })
}

let hasActiveJobs: pDefer.DeferredPromise<void> | null = null

function hasExternalJobsEnabled(): boolean {
  return (
    process.env.ENABLE_GATSBY_EXTERNAL_JOBS === `true` ||
    process.env.ENABLE_GATSBY_EXTERNAL_JOBS === `1`
  )

View on GitHub (pinned to 8b06340921)

Solutions

1. Resolve to absolute before enqueueing: path.resolve(__dirname, rel).
2. Use path.join(process.cwd(), rel) when the file is project-relative.
3. Normalize with the slash() helper for cross-platform consistency.

Example fix

// before
const job = actions.createJob({ name: `PROCESS_IMAGE`, inputPaths: ['./img.png'], outputDir })
// after
const path = require('path')
const job = actions.createJob({ name: `PROCESS_IMAGE`, inputPaths: [path.resolve(__dirname, 'img.png')], outputDir })

const path = require('path')
function ensureAbsolute(filePath) {
  if (!path.isAbsolute(filePath)) throw new Error(`Expected absolute path, got ${filePath}`)
  return filePath
}

function isAbsolutePath(p) { return typeof p === 'string' && path.isAbsolute(p) }

When it happens

Trigger: A plugin enqueues a job (e.g. image transformation, sharp processing) passing a relative inputPath like './src/img.png' or 'img/foo.png'.

Common situations: Plugin passing __dirname-relative or cwd-relative paths; cross-platform path separators; plugin authored without path.resolve.

Related errors

• starter ${starterPath} doesn't exist
• Couldn't find the specified offline inject script
• PageCreator: To query node "gatsbyPath" the "filePath" argum
• Failed to load image ${file} into sharp.
• Failed to write ${file} into ${outputPath}. (${err.message})

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