parcel-bundler/parcel · error · Error

Please provide a worker path!

Error message

Please provide a worker path!

What it means

Thrown by WorkerFarm constructor when options.workerPath is falsy. The worker farm requires a path to the worker entry module to spawn child workers (or to load the local worker in-process); without it the farm cannot initialize, so it fails immediately.

Source

Thrown at packages/core/workers/src/WorkerFarm.js:103

  serializedSharedReferences: Map<SharedReference, ?ArrayBuffer> = new Map();
  profiler: ?SamplingProfiler;

  constructor(farmOptions: $Shape<FarmOptions> = {}) {
    super();
    this.options = {
      maxConcurrentWorkers: WorkerFarm.getNumWorkers(),
      maxConcurrentCallsPerWorker: WorkerFarm.getConcurrentCallsPerWorker(
        farmOptions.shouldTrace ? 1 : DEFAULT_MAX_CONCURRENT_CALLS,
      ),
      forcedKillTime: 500,
      warmWorkers: false,
      useLocalWorker: true, // TODO: setting this to false makes some tests fail, figure out why
      backend: detectBackend(),
      ...farmOptions,
    };

    if (!this.options.workerPath) {
      throw new Error('Please provide a worker path!');
    }

    // $FlowFixMe
    if (process.browser) {
      if (this.options.workerPath === '@parcel/core/src/worker.js') {
        this.localWorker = coreWorker;
      } else {
        throw new Error(
          'No dynamic require possible: ' + this.options.workerPath,
        );
      }
    } else {
      // $FlowFixMe this must be dynamic
      this.localWorker = require(this.options.workerPath);
    }

    this.localWorkerInit =
      this.localWorker.childInit != null ? this.localWorker.childInit() : null;

View on GitHub (pinned to 59484858a1)

Solutions

1. Pass workerPath in options, e.g. `new WorkerFarm({ workerPath: require.resolve('@parcel/core/src/worker.js'), ... })`.
2. Use WorkerFarm.getShared() instead of constructing directly so Parcel fills in defaults.
3. If integrating programmatically, ensure your wrapper forwards workerPath from its caller.

Example fix

// before
const farm = new WorkerFarm({ maxConcurrentWorkers: 4 });

// after
const farm = new WorkerFarm({
  workerPath: require.resolve('@parcel/core/src/worker.js'),
  maxConcurrentWorkers: 4,
});

if (!options.workerPath) {
  throw new Error('workerPath is required by WorkerFarm');
}
const farm = new WorkerFarm({ workerPath: require.resolve('@parcel/core/src/worker.js'), ...options });

interface WorkerFarmOpts { workerPath: string; }
function hasWorkerPath(o: unknown): o is WorkerFarmOpts {
  return typeof (o as any)?.workerPath === 'string' && (o as any).workerPath.length > 0;
}

When it happens

Trigger: Constructing `new WorkerFarm({})` (or with an options object that omits workerPath); calling WorkerFarm.getFromOptions with a config missing the workerPath field; programmatic use of @parcel/workers without setting the worker entry.

Common situations: Custom integrations that spin up WorkerFarm directly; passing only farmOptions like maxConcurrentWorkers while forgetting workerPath; refactor that drops the field.

Related errors

• No dynamic require possible: ${workerPath}
• Invalid backend: ${backend}
• Supplied WorkerFarm is ending
• Targets option is an empty array
• Missing distDir for target "${name}"

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/1eb3d02bb6905b67. Report an issue: GitHub.