mochajs/mocha · error · Error

This script is intended to be run as a worker (by the `worke

Error message

This script is intended to be run as a worker (by the `workerpool` package).

What it means

Mocha's parallel-mode worker script (lib/nodejs/worker.cjs) is designed to be loaded by the `workerpool` package inside a worker thread, not executed directly. At module load it checks `workerpool.isMainThread`; if the script is running on the main thread it means it was required or executed outside of a workerpool worker, so it throws immediately to prevent the worker bootstrap logic (root hooks, run loop) from running in the wrong context.

Source

Thrown at lib/nodejs/worker.cjs:33

  createInvalidArgumentTypeError,
  createInvalidArgumentValueError,
} = require("../errors.js");
const workerpool = require("workerpool");
const Mocha = require("../mocha.cjs");
const {
  handleRequires,
  validateLegacyPlugin,
} = require("../cli/run-helpers.cjs");
const d = require("debug");
const debug = d.debug(`mocha:parallel:worker:${process.pid}`);
const isDebugEnabled = d.enabled(`mocha:parallel:worker:${process.pid}`);
const { serialize } = require("./serializer.js");
const { setInterval, clearInterval } = global;

let rootHooks;

if (workerpool.isMainThread) {
  throw new Error(
    "This script is intended to be run as a worker (by the `workerpool` package).",
  );
}

/**
 * Initializes some stuff on the first call to {@link run}.
 *
 * Handles `--require` and `--ui`.  Does _not_ handle `--reporter`,
 * as only the `Buffered` reporter is used.
 *
 * **This function only runs once per worker**; it overwrites itself with a no-op
 * before returning.
 *
 * @param {MochaOptions} argv - Command-line options
 */
let bootstrap = async (argv) => {
  // globalSetup and globalTeardown do not run in workers
  const plugins = await handleRequires(argv.require, {

View on GitHub (pinned to 6bcbee4fd9)

Solutions

1. Run mocha normally with `--parallel` and let mocha/workerpool spawn the worker internally
2. If building a custom runner, load the worker via workerpool (e.g. `workerpool.worker(...)`) inside a worker thread, not on the main thread
3. Remove any direct `require('mocha/lib/nodejs/worker.cjs')` from application code
4. Use the public Mocha programmatic API or CLI instead of internal worker modules

Example fix

// before
const worker = require('mocha/lib/nodejs/worker.cjs');
// after
const Mocha = require('mocha');
const mocha = new Mocha({ parallel: true });
mocha.run();

if (workerpool.isMainThread) {
  // do not load the worker module on the main thread
} else {
  require('mocha/lib/nodejs/worker.cjs');
}

const isWorkerThread = typeof workerpool !== 'undefined' && !workerpool.isMainThread;

try {
  require('mocha/lib/nodejs/worker.cjs');
} catch (err) {
  if (!/intended to be run as a worker/.test(err.message)) throw err;
  console.error('worker.cjs must be spawned by workerpool, not required directly');
}

When it happens

Trigger: Running `node lib/nodejs/worker.cjs` directly; `require()`-ing worker.cjs from user code or a test on the main thread; launching the parallel runner with a custom/incorrect worker path that resolves to this file in the main thread.

Common situations: Users point `--parallel` at the wrong file or write custom runners that spawn mocha's worker themselves; debugging sessions where a developer opens/executes the worker file directly; bundlers or module loaders accidentally pulling worker.cjs into the main bundle.

Related errors

• ERR_MOCHA_INVALID_ARG_TYPE

AI-assisted analysis of mochajs/mocha@6bcbee4fd9 (2026-09-01). Data as JSON: /api/errors/ba26d3aa11c0973d. Report an issue: GitHub.