mochajs/mocha · error · InvalidInterfaceError

ERR_MOCHA_INVALID_INTERFACE

ERR_MOCHA_INVALID_INTERFACE

Error message

invalid interface '${ui}'

What it means

Mocha.ui() selects a built-in interface (bdd, tdd, qunit, exports) from exports.interfaces; if the name is unknown it attempts require(ui) to load a third-party interface module. If that require also fails, createInvalidInterfaceError throws with "invalid interface '<ui>'".

Source

Thrown at lib/mocha.cjs:372

 * @see [CLI option](../#-ui-name-u-name)
 * @see [Interface DSLs](../#interfaces)
 * @param {string|Function} [ui=bdd] - Interface name or class.
 * @returns {Mocha} this
 * @chainable
 * @throws {Error} if requested interface cannot be loaded
 */
Mocha.prototype.ui = function (ui) {
  var bindInterface;
  if (typeof ui === "function") {
    bindInterface = ui;
  } else {
    ui = ui || "bdd";
    bindInterface = exports.interfaces[ui];
    if (!bindInterface) {
      try {
        bindInterface = require(ui);
      } catch {
        throw createInvalidInterfaceError(`invalid interface '${ui}'`, ui);
      }
    }
  }
  if (bindInterface.default) {
    bindInterface = bindInterface.default;
  }

  bindInterface(this.suite);

  this.suite.on(EVENT_FILE_PRE_REQUIRE, function (context) {
    currentContext = context;
  });

  return this;
};

/**
 * Loads `files` prior to execution. Does not support ES Modules.

View on GitHub (pinned to 6bcbee4fd9)

Solutions

1. Use a built-in interface name: bdd (default), tdd, qunit, or exports
2. Check spelling in .mocharc or the --ui flag
3. Install the third-party interface package if you intend to use one, ensuring require(ui) resolves
4. Remove the ui override to fall back to the default bdd interface

Example fix

// before
const mocha = new Mocha({ ui: 'bdd2' });
// after
const mocha = new Mocha({ ui: 'bdd' });

const BUILTIN_UIS = ['bdd', 'tdd', 'qunit', 'exports'];
if (ui && !BUILTIN_UIS.includes(ui)) {
  try { require.resolve(ui); } catch {
    throw new Error(`Unknown ui '${ui}'`);
  }
}

try {
  new Mocha({ ui });
} catch (err) {
  if (err.code === 'ERR_MOCHA_INVALID_INTERFACE') {
    console.error(`Invalid ui '${ui}'; use bdd, tdd, qunit, exports or install the interface package`);
  } else throw err;
}

When it happens

Trigger: `new Mocha({ui: 'typo'})`, `mocha --ui nonexistent`, or a mocharc config with an ui value that is neither built-in nor an installable module.

Common situations: Misspelled ui names (e.g., 'tdd' vs 'tds'); assuming custom UIs are built in; config merging renaming the ui value; third-party interface package not installed.

Related errors

• ERR_MOCHA_UNPARSABLE_FILE
• ERR_MOCHA_UNPARSABLE_FILE
• ERR_MOCHA_INVALID_REPORTER (reporter) or ERR_MOCHA_INVALID_INTERFACE (ui)

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