mochajs/mocha · error · MissingArgumentError

ERR_MOCHA_MISSING_ARGUMENT

ERR_MOCHA_MISSING_ARGUMENT

Error message

"--invert" requires one of "--fgrep <str>" or "--grep <regexp>"

What it means

The --invert flag negates the test-file/name filter, so it requires a filter to invert (--grep or --fgrep). validateRunOptions throws createMissingArgumentError when --invert is present but neither filter option is supplied.

Source

Thrown at lib/cli/run.cjs:91

  // "one-and-dones"; help and version are handled by the top-level CLI.
  const oneAndDoneOptions = Object.keys(ONE_AND_DONES).filter((opt) =>
    Boolean(argv[opt]),
  );
  if (oneAndDoneOptions.length > 1) {
    throw createUnsupportedError(
      `Arguments ${oneAndDoneOptions.join(" and ")} are mutually exclusive`,
    );
  }

  Object.keys(ONE_AND_DONES).forEach((opt) => {
    if (argv[opt]) {
      ONE_AND_DONES[opt].call(null);
      process.exit(0);
    }
  });

  if (argv.invert && !("fgrep" in argv || "grep" in argv)) {
    throw createMissingArgumentError(
      '"--invert" requires one of "--fgrep <str>" or "--grep <regexp>"',
      "--fgrep|--grep",
      "string|regexp",
    );
  }

  if (argv.fgrep && argv.grep) {
    throw createUnsupportedError(
      "Arguments fgrep and grep are mutually exclusive",
    );
  }

  if (argv.parallel) {
    if (argv.file) {
      throw createUnsupportedError(
        "--parallel runs test files in a non-deterministic order, and is mutually exclusive with --file",
      );
    }

View on GitHub (pinned to 6bcbee4fd9)

Solutions

1. Add a filter: pass --grep <regexp> or --fgrep <str> alongside --invert
2. If no filtering is wanted, remove --invert entirely
3. Fix typos in the flag name so the grep/fgrep value is actually parsed

Example fix

// before
mocha --invert
// after
mocha --grep "auth" --invert

if (argv.invert && !argv.grep && !argv.fgrep) {
  throw new Error('--invert requires --grep or --fgrep');
}

try {
  mochaRun(argv);
} catch (err) {
  if (err.code === 'ERR_MOCHA_MISSING_ARGUMENT') {
    console.error(err.message);
    process.exitCode = 1;
  } else throw err;
}

When it happens

Trigger: Running `mocha --invert` (or passing argv {invert:true}) without also passing --grep <regexp> or --fgrep <str>.

Common situations: Editing an npm script and deleting the --grep part but keeping --invert; templated CI scripts where the grep parameter is empty and only --invert survives; typos like --grepp.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

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

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