mochajs/mocha · error · MochaInstanceAlreadyDisposedError

ERR_MOCHA_INSTANCE_ALREADY_DISPOSED

ERR_MOCHA_INSTANCE_ALREADY_DISPOSED

Error message

Mocha instance is already disposed, it cannot be used again.

What it means

Mocha tracks instance state; once dispose() (or an equivalent cleanup path) has marked the instance DISPOSED, any further use is rejected. unloadFiles() is called during dispose and at the start of run(), so calling it on a disposed instance throws. Mocha throws this to prevent using stale instances whose test function references may have been cleaned for GC.

Source

Thrown at lib/mocha.cjs:490

/**
 * 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}
 * @returns {Mocha} this
 * @chainable
 */
Mocha.prototype.unloadFiles = function () {
  if (this._state === mochaStates.DISPOSED) {
    throw createMochaInstanceAlreadyDisposedError(
      "Mocha instance is already disposed, it cannot be used again.",
      this._cleanReferencesAfterRun,
      this,
    );
  }

  this.files.forEach(function (file) {
    Mocha.unloadFile(file);
  });
  this._state = mochaStates.INIT;
  return this;
};

/**
 * Sets `grep` filter after escaping RegExp special characters.
 *
 * @public
 * @see {@link Mocha#grep}

View on GitHub (pinned to 6bcbee4fd9)

Solutions

1. Create a new Mocha instance instead of reusing the disposed one
2. Set cleanReferencesAfterRun: false in options if you intentionally want to reuse one instance across runs
3. Guard with a state check or a try/catch before reusing an instance you may have disposed

Example fix

// before
const mocha = new Mocha();
await runOnce(mocha);
mocha.dispose();
mocha.unloadFiles(); // throws
// after
const mocha = new Mocha();
await runOnce(mocha);
mocha.dispose();
const mocha2 = new Mocha(); // fresh instance for further use
mocha2.unloadFiles();

// check state before use
if (mocha._state === 'disposed' || mocha._state === 'references-cleaned') {
  mocha = new Mocha(options);
}

function isUsable(mocha) {
  return mocha && mocha._state !== 'disposed' && mocha._state !== 'references-cleaned';
}

try {
  mocha.unloadFiles();
} catch (err) {
  if (err.code === 'ERR_MOCHA_INSTANCE_ALREADY_DISPOSED') {
    mocha = new Mocha(options);
  } else {
    throw err;
  }
}

When it happens

Trigger: Calling mocha.unloadFiles() (or any API that calls it, e.g. dispose() or a second run()) on a Mocha instance whose _state is mochaStates.DISPOSED.

Common situations: Programmatic usage that reuses one Mocha instance across multiple runs after calling dispose(); test runners/IDE integrations holding a disposed instance; calling unloadFiles() twice.

Related errors

• ERR_MOCHA_INSTANCE_ALREADY_RUNNING
• ERR_MOCHA_INVALID_ARG_TYPE
• ERR_MOCHA_FATAL
• ERR_MOCHA_INVALID_ARG_TYPE

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