{"record":{"id":"a9fa175fc3277eb3","repo":"gatsbyjs/gatsby","slug":"filepath-should-be-an-absolute-path","errorCode":null,"errorMessage":"${filePath} should be an absolute path.","messagePattern":"(.+?) should be an absolute path\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/gatsby/src/utils/jobs/manager.ts","lineNumber":47,"sourceCode":"let activeJobs = 0\nlet isListeningForMessages = false\nlet hasShownIPCDisabledWarning = false\n\nconst jobsInProcess: Map<\n  string,\n  { id: string; deferred: pDefer.DeferredPromise<Record<string, unknown>> }\n> = new Map()\nconst externalJobsMap: Map<\n  string,\n  { job: InternalJob; deferred: pDefer.DeferredPromise<any> }\n> = new Map()\n\n/**\n * We want to use absolute paths to make sure they are on the filesystem\n */\nfunction convertPathsToAbsolute(filePath: string): string {\n  if (!path.isAbsolute(filePath)) {\n    throw new Error(`${filePath} should be an absolute path.`)\n  }\n\n  return slash(filePath)\n}\n/**\n * Get contenthash of a file\n */\nfunction createFileHash(path: string): string {\n  return hasha.fromFileSync(path, { algorithm: `sha1` })\n}\n\nlet hasActiveJobs: pDefer.DeferredPromise<void> | null = null\n\nfunction hasExternalJobsEnabled(): boolean {\n  return (\n    process.env.ENABLE_GATSBY_EXTERNAL_JOBS === `true` ||\n    process.env.ENABLE_GATSBY_EXTERNAL_JOBS === `1`\n  )","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/utils/jobs/manager.ts#L29-L65","documentation":"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.","triggerScenarios":"A plugin enqueues a job (e.g. image transformation, sharp processing) passing a relative inputPath like './src/img.png' or 'img/foo.png'.","commonSituations":"Plugin passing __dirname-relative or cwd-relative paths; cross-platform path separators; plugin authored without path.resolve.","solutions":["Resolve to absolute before enqueueing: path.resolve(__dirname, rel).","Use path.join(process.cwd(), rel) when the file is project-relative.","Normalize with the slash() helper for cross-platform consistency."],"exampleFix":"// before\nconst job = actions.createJob({ name: `PROCESS_IMAGE`, inputPaths: ['./img.png'], outputDir })\n// after\nconst path = require('path')\nconst job = actions.createJob({ name: `PROCESS_IMAGE`, inputPaths: [path.resolve(__dirname, 'img.png')], outputDir })","handlingStrategy":"validation","validationCode":"const path = require('path')\nfunction ensureAbsolute(filePath) {\n  if (!path.isAbsolute(filePath)) throw new Error(`Expected absolute path, got ${filePath}`)\n  return filePath\n}","typeGuard":"function isAbsolutePath(p) { return typeof p === 'string' && path.isAbsolute(p) }","tryCatchPattern":null,"preventionTips":["Always path.resolve(__dirname, rel) before enqueueing jobs.","Use the slash() helper for cross-platform path normalization.","Lint plugins for raw relative paths in createJob calls."],"tags":["jobs","filesystem","paths"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}