parcel-bundler/parcel · error · Error

Invalid backend: ${backend}

Error message

Invalid backend: ${backend}

What it means

Thrown by getWorkerBackend when the backend argument is not one of 'threads', 'process', or 'web'. The function maps a BackendType to a worker implementation class; an unknown value (or undefined) hits the default branch.

Source

Thrown at packages/core/workers/src/backend.js:31

  try {
    require('worker_threads');
    return 'threads';
  } catch (err) {
    return 'process';
  }
}

export function getWorkerBackend(backend: BackendType): Class<WorkerImpl> {
  switch (backend) {
    case 'threads':
      return require('./threads/ThreadsWorker').default;
    case 'process':
      return require('./process/ProcessWorker').default;
    case 'web':
      return require('./web/WebWorker').default;
    default:
      throw new Error(`Invalid backend: ${backend}`);
  }
}

View on GitHub (pinned to 59484858a1)

Solutions

1. Set PARCEL_WORKER_BACKEND to 'threads' or 'process' (or omit it to auto-detect).
2. If passing backend in farmOptions, use one of 'threads' | 'process' | 'web'.
3. Unset the env var and let detectBackend() choose automatically.

Example fix

// before
PARCEL_WORKER_BACKEND=thread parcel build   // typo
// or
new WorkerFarm({ backend: 'cluster' });

// after
PARCEL_WORKER_BACKEND=process parcel build
// or
new WorkerFarm({ backend: 'process' });

const VALID_BACKENDS = new Set(['threads','process','web']);
function normalizeBackend(b) {
  if (b && !VALID_BACKENDS.has(b)) {
    throw new Error(`Invalid backend '${b}'; use threads|process|web.`);
  }
  return b;
}

type BackendType = 'threads'|'process'|'web';
function isValidBackend(b: string): b is BackendType {
  return b === 'threads' || b === 'process' || b === 'web';
}

When it happens

Trigger: Passing PARCEL_WORKER_BACKEND with a typo/invalid value (e.g. 'thread', 'processes', 'worker'), or constructing WorkerFarm with an explicit backend option that is not in the allowed set.

Common situations: Setting PARCEL_WORKER_BACKEND incorrectly; programmatic API misuse passing backend:'cluster'; stale docs suggesting an unsupported backend name.

Related errors

• Please provide a worker path!
• Supplied WorkerFarm is ending
• No dynamic require possible: ${workerPath}
• No dynamic require possible: ${location}
• Cannot add a worker call if workerfarm is ending.

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