mochajs/mocha · error · UnsupportedError

ERR_MOCHA_UNSUPPORTED

ERR_MOCHA_UNSUPPORTED

Error message

Arguments ${oneAndDoneOptions.join(" and ")} are mutually exclusive

What it means

Mocha's CLI validates run options before starting and refuses to run when more than one 'one-and-done' flag (--help, --version, --list-interfaces, --list-reporters) is supplied. These flags print info and exit immediately, so combining them is meaningless. Mocha throws createUnsupportedError naming the conflicting flags.

Source

Thrown at lib/cli/run.cjs:78

      const normalizedName = camelCase(name);
      if (!(normalizedName in argv)) {
        argv[normalizedName] = argv[name];
      }
    }
  });

  if (Array.isArray(argv["reporter-option"])) {
    argv["reporter-option"] = coerceReporterOption(argv["reporter-option"]);
  }
};

const validateRunOptions = (argv) => {
  // "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",
    );
  }

View on GitHub (pinned to 6bcbee4fd9)

Solutions

1. Remove one of the conflicting one-and-done flags so only a single flag like --help or --version is passed
2. Audit the script/alias that composes the mocha command line and fix flag concatenation
3. If invoking programmatically, ensure the argv object sets only one of the ONE_AND_DONES keys truthy

Example fix

// before
mocha --help --version
// after
mocha --help

const ONE_AND_DONES = ['help','h','version','V','list-interfaces','list-reporters'];
const active = ONE_AND_DONES.filter((o) => argv[o]);
if (active.length > 1) throw new Error(`Pick only one of: ${active.join(', ')}`);

try {
  mochaRun(argv);
} catch (err) {
  if (err.code === 'ERR_MOCHA_UNSUPPORTED') {
    console.error(`Fix CLI flags: ${err.message}`);
    process.exitCode = 1;
  } else throw err;
}

When it happens

Trigger: Running the mocha CLI with two or more truthy one-and-done options in argv, e.g. `mocha --help --version` or `mocha --list-reporters --list-interfaces`; programmatically, calling run() with an argv object where multiple ONE_AND_DONES keys are truthy.

Common situations: Shell scripts or npm scripts appending flags so two info flags end up together; wrappers passing argv objects where leftover truthy values from a previous config remain; alias confusion like -V vs --version duplicates.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

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

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