gatsbyjs/gatsby · error

We couldn't find a gatsby-worker.js(${plugin.resolve}/gatsby

Error message

We couldn't find a gatsby-worker.js(${plugin.resolve}/gatsby-worker.js) file for ${plugin.name}@${plugin.version}

What it means

runJob wraps importGatsbyPlugin(plugin, 'gatsby-worker') in a try/catch; any failure (module not found, require-time error) is re-thrown as this generic message. It means the plugin ships no loadable gatsby-worker.js at plugin.resolve, or that file threw on require.

Source

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

            isListeningForMessages = true
            listenForJobMessages()
          }

          return runExternalWorker(job)
        } else {
          // only show the offloading warning once
          if (!hasShownIPCDisabledWarning) {
            hasShownIPCDisabledWarning = true
            reporter.warn(
              `Offloading of a job failed as IPC could not be detected. Running job locally.`
            )
          }
        }
      }
      return runLocalWorker(worker[job.name], job)
    })
  } catch (err) {
    throw new Error(
      `We couldn't find a gatsby-worker.js(${plugin.resolve}/gatsby-worker.js) file for ${plugin.name}@${plugin.version}`
    )
  }
}

function isInternalJob(job: JobInput | InternalJob): job is InternalJob {
  return (
    (job as InternalJob).id !== undefined &&
    (job as InternalJob).contentDigest !== undefined
  )
}

/**
 * Create an internal job object
 */
export function createInternalJob(
  job: JobInput | InternalJob,
  plugin: { name: string; version: string; resolve: string }

View on GitHub (pinned to 8b06340921)

Solutions

1. Reinstall the plugin (npm/yarn install) so gatsby-worker.js is present.
2. Confirm gatsby-worker.js exists at plugin.resolve and is a valid CommonJS module.
3. Upgrade or pin a plugin version known to ship the worker file.
4. Open the worker file in node to see the underlying require error and fix it.

const fs = require('fs')
const path = require('path')
function pluginHasWorkerFile(plugin) {
  return fs.existsSync(path.join(plugin.resolve, 'gatsby-worker.js'))
}

function workerFileResolves(plugin) {
  try { require.resolve(path.join(plugin.resolve, 'gatsby-worker.js')); return true } catch { return false }
}

When it happens

Trigger: The plugin package lacks gatsby-worker.js at its root; plugin.resolve points to the wrong directory; the worker module itself throws at require-time.

Common situations: Missing worker file in the published package; monorepo/yarn-link resolution issue; broken plugin install; worker file has a syntax/runtime error during load.

Related errors

• No worker function found for ${job.name}
• Result of a worker should be an object, type of "${typeof re
• An ID must be provided when creating or setting job
• An ID must be provided when ending a job
• The plugin "${_.get(action, `plugin.name`, `anonymous`)}" tr

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