mochajs/mocha · error · UnsupportedError

ERR_MOCHA_UNSUPPORTED

ERR_MOCHA_UNSUPPORTED

Error message

unloadFile() is only supported in a Node.js environment

What it means

Mocha.unloadFile() removes a test file's module from the require cache so it can be re-required; this relies on Node's require cache and cannot work in browsers. Calling it where utils.isBrowser() is true throws createUnsupportedError.

Source

Thrown at lib/mocha.cjs:466

    function (file, resultModule) {
      suite.emit(EVENT_FILE_REQUIRE, resultModule, file, self);
      suite.emit(EVENT_FILE_POST_REQUIRE, global, file, self);
    },
    esmDecorator,
  );
};

/**
 * Removes a previously loaded file from Node's `require` cache.
 *
 * @private
 * @static
 * @see {@link Mocha#unloadFiles}
 * @param {string} file - Pathname of file to be unloaded.
 */
Mocha.unloadFile = function (file) {
  if (utils.isBrowser()) {
    throw createUnsupportedError(
      "unloadFile() is only supported in a Node.js environment",
    );
  }
  return require("./nodejs/file-unloader.cjs").unloadFile(file);
};

/**
 * Unloads `files` from Node's `require` cache.
 *
 * @description
 * This allows required files to be "freshly" reloaded, providing the ability
 * to reuse a Mocha instance programmatically.
 * Note: does not clear ESM module files from the cache
 *
 * <strong>Intended for consumers &mdash; not used internally</strong>
 *
 * @public
 * @see {@link Mocha#run}

View on GitHub (pinned to 6bcbee4fd9)

Solutions

1. Only call unloadFile/unloadFiles in Node; guard with a Node environment check before calling
2. Skip the unload step in browser builds (browser Mocha has no require cache to clear)
3. If unloading is needed for watch mode, ensure that code path runs only in the Node CLI, not the browser bundle

Example fix

// before
Mocha.unloadFile(file);
// after
if (!utils.isBrowser()) {
  Mocha.unloadFile(file);
}

if (typeof process === 'undefined' || typeof require === 'undefined') {
  // browser: do not call unloadFile/unloadFiles
}

function isNode() {
  return (
    typeof process !== 'undefined' &&
    process.versions != null &&
    process.versions.node != null
  );
}
if (isNode()) Mocha.unloadFile(file);

try {
  Mocha.unloadFile(file);
} catch (err) {
  if (err.code === 'ERR_MOCHA_UNSUPPORTED') {
    // browser environment: skip unloading
  } else throw err;
}

When it happens

Trigger: Calling Mocha.unloadFile(file) or mocha.unloadFiles() from browser-bundled Mocha (e.g., inside a browser test runner page or bundle that includes the nodejs/unloadFile static).

Common situations: Sharing one test harness setup code between Node and browser builds; calling unloadFiles in watch-mode helpers that also run in the browser; bundlers pulling node-only Mocha APIs into browser code.

Related errors

• ERR_MOCHA_INVALID_PLUGIN_DEFINITION
• ERR_MOCHA_UNSUPPORTED
• ERR_MOCHA_UNSUPPORTED

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