mochajs/mocha · error · InvalidArgumentTypeError

ERR_MOCHA_INVALID_ARG_TYPE

ERR_MOCHA_INVALID_ARG_TYPE

Error message

Expected a non-empty "filepath" argument

What it means

The worker-side run() function (executed inside the worker process) validates that a filepath was provided before loading the test file. An empty/undefined filepath throws ERR_MOCHA_INVALID_ARG_TYPE with parameter name 'file'.

Source

Thrown at lib/nodejs/worker.cjs:71

  });
  validateLegacyPlugin(argv, "ui", Mocha.interfaces);

  rootHooks = plugins.rootHooks;
  bootstrap = () => {};
  debug("bootstrap(): finished with args: %O", argv);
};

/**
 * Runs a single test file in a worker thread.
 * @param {string} filepath - Filepath of test file
 * @param {string} [serializedOptions] - **Serialized** options. This string will be eval'd!
 * @see https://npm.im/serialize-javascript
 * @returns {Promise<{failures: number, events: BufferedEvent[]}>} - Test
 * failure count and list of events.
 */
async function run(filepath, serializedOptions = "{}") {
  if (!filepath) {
    throw createInvalidArgumentTypeError(
      'Expected a non-empty "filepath" argument',
      "file",
      "string",
    );
  }

  debug("run(): running test file %s", filepath);

  if (typeof serializedOptions !== "string") {
    throw createInvalidArgumentTypeError(
      "run() expects second parameter to be a string which was serialized by the `serialize-javascript` module",
      "serializedOptions",
      "string",
    );
  }
  let argv;
  try {
    argv = eval("(" + serializedOptions + ")");

View on GitHub (pinned to 6bcbee4fd9)

Solutions

1. Pass a valid non-empty string filepath to run()
2. Fix upstream code that resolves test files so it never dispatches empty paths
3. Align mocha versions if the error appears during normal --parallel runs

Example fix

// before
worker.run(filePath); // filePath could be ''
// after
if (typeof filePath === 'string' && filePath) {
  await worker.run(filePath);
}

if (typeof filepath === 'string' && filepath) {
  await worker.run(filepath, serializedOptions);
}

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

try {
  await worker.run(filepath, serializedOptions);
} catch (err) {
  if (err.code === 'ERR_MOCHA_INVALID_ARG_TYPE') {
    console.error('worker.run received invalid filepath:', filepath);
  } else {
    throw err;
  }
}

When it happens

Trigger: Calling worker.run('') or worker.run(undefined), or a worker receiving a truncated/incorrect message where the filepath argument is missing.

Common situations: Direct/programmatic use of lib/nodejs/worker; protocol bugs in worker messaging; empty glob expansion upstream.

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/7c35aeccfe5717c9. Report an issue: GitHub.