What causes "Missing runner argument" in mochajs/mocha?

Pass the actual runner instance: `createStatsCollector(runner)`.

mochajs/mocha · error · TypeError

Missing runner argument

Error message

Missing runner argument

What it means

`createStatsCollector` attaches a stats object and event listeners (RUN_BEGIN/RUN_END/PASS/FAIL etc.) to a runner instance, so it requires the runner as its argument. A `TypeError` is thrown when called with undefined/null, indicating the runner was never created or wasn't passed through.

Source

Thrown at lib/stats-collector.js:43

 *
 * @private
 * @param {Runner} runner - Runner instance
 * @throws {TypeError} If falsy `runner`
 */
function createStatsCollector(runner) {
  /**
   * @type {StatsCollector}
   */
  var stats = {
    suites: 0,
    tests: 0,
    passes: 0,
    pending: 0,
    failures: 0,
  };

  if (!runner) {
    throw new TypeError("Missing runner argument");
  }

  runner.stats = stats;

  runner.once(EVENT_RUN_BEGIN, function () {
    stats.start = new Date();
  });
  runner.on(EVENT_SUITE_BEGIN, function (suite) {
    suite.root || stats.suites++;
  });
  runner.on(EVENT_TEST_PASS, function () {
    stats.passes++;
  });
  runner.on(EVENT_TEST_FAIL, function () {
    stats.failures++;
  });
  runner.on(EVENT_TEST_PENDING, function () {
    stats.pending++;

View on GitHub (pinned to 6bcbee4fd9)

Solutions

Pass the actual runner instance: `createStatsCollector(runner)`.
Only invoke after a Runner exists — e.g. inside/after `mocha.run(cb)` or `new Runner(suite)`.
If building custom runners, ensure it's a real EventEmitter-like object with the expected Mocha events.

Example fix

// before
const runner = new Runner(suite);
createStatsCollector(); // TypeError

// after
const runner = new Runner(suite);
createStatsCollector(runner);

Defensive patterns

Strategy: type-guard

Validate before calling

if (!runner) {
  throw new Error('createStatsCollector requires a runner instance');
}

Type guard

const looksLikeRunner = (r) => r != null && typeof r.once === 'function' && typeof r.on === 'function' && typeof r.emit === 'function';

Try / catch

try {
  createStatsCollector(runner);
} catch (err) {
  if (err instanceof TypeError && err.message === 'Missing runner argument') {
    console.error('Pass the Runner instance from mocha.run() to createStatsCollector.');
  }
  throw err;
}

Prevention

Create the Runner via mocha.run() and pass it through immediately.
In wrappers, thread the runner argument explicitly instead of relying on closures.
Never call stats collection before the runner exists.
Add an assertion in tooling that the runner is an EventEmitter before wiring stats.

When it happens

Trigger: `createStatsCollector()` with no args; `createStatsCollector(null)`; integration code that builds a fake runner but forgets to pass it; calling the collector before `mocha.run()` creates the Runner.

Common situations: Custom reporter/tooling setups that wire Mocha internals manually; test harness wrappers calling `createStatsCollector` without the runner from `mocha.run()`; refactors that drop the argument when the runner is created lazily.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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