mochajs/mocha · error · InvalidArgumentTypeError

ERR_MOCHA_INVALID_ARG_TYPE

ERR_MOCHA_INVALID_ARG_TYPE

Error message

Expected a non-empty filepath

What it means

BufferedWorkerPool.run() validates its filepath argument before dispatching work to a worker pool. It requires a non-empty string; otherwise it throws ERR_MOCHA_INVALID_ARG_TYPE naming filepath as the offending argument.

Source

Thrown at lib/nodejs/buffered-worker-pool.cjs:128

  async terminate(force = false) {
    /* istanbul ignore next */
    debug("terminate(): terminating with force = %s", force);
    return this._pool.terminate(force);
  }

  /**
   * Adds a test file run to the worker pool queue for execution by a worker process.
   *
   * Handles serialization/deserialization.
   *
   * @param {string} filepath - Filepath of test
   * @param {MochaOptions} [options] - Options for Mocha instance
   * @private
   * @returns {Promise<SerializedWorkerResult>}
   */
  async run(filepath, options = {}) {
    if (!filepath || typeof filepath !== "string") {
      throw createInvalidArgumentTypeError(
        "Expected a non-empty filepath",
        "filepath",
        "string",
      );
    }
    const serializedOptions = BufferedWorkerPool.serializeOptions(options);
    const result = await this._pool.exec("run", [filepath, serializedOptions]);
    return deserialize(result);
  }

  /**
   * Returns stats about the state of the worker processes in the pool.
   *
   * Used for debugging.
   *
   * @private
   */
  stats() {

View on GitHub (pinned to 6bcbee4fd9)

Solutions

1. Ensure the filepath exists and is a non-empty string before calling run()
2. Check upstream glob/CLI parsing so an empty match list is handled before dispatch
3. Wrap run() in try/catch and log/queue the invalid file instead of crashing the pool

Example fix

// before
await pool.run(files[0]); // files may be empty -> undefined
// after
const file = files[0];
if (typeof file === 'string' && file.length > 0) {
  await pool.run(file);
}

if (typeof filepath === 'string' && filepath.length > 0) {
  await pool.run(filepath, options);
}

function isNonEmptyString(v) {
  return typeof v === 'string' && v.length > 0;
}

try {
  await pool.run(filepath, options);
} catch (err) {
  if (err.code === 'ERR_MOCHA_INVALID_ARG_TYPE') {
    console.error('Invalid filepath passed to worker pool:', filepath);
  } else {
    throw err;
  }
}

When it happens

Trigger: Calling bufferedWorkerPool.run(undefined/null/''/non-string) — e.g. when a file-glob resolved to nothing or a variable holding the path was not assigned.

Common situations: Parallel-mode file resolution producing empty results; programmatic parallel runners passing a bad entry; glob expansion returning an empty array and code doing files[0] on it.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• ERR_MOCHA_INVALID_ARG_TYPE
• ERR_MOCHA_FATAL
• Not enough non-option arguments: got 0, need at least 1
• Not enough arguments following: ${name}
• Missing runner argument

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