{"record":{"id":"782e9a0b765f753f","repo":"mochajs/mocha","slug":"err-mocha-instance-already-disposed","errorCode":"ERR_MOCHA_INSTANCE_ALREADY_DISPOSED","errorMessage":"Mocha instance is already disposed, it cannot be used again.","messagePattern":"Mocha instance is already disposed, it cannot be used again\\.","errorType":"exception","errorClass":"MochaInstanceAlreadyDisposedError","httpStatus":null,"severity":"error","filePath":"lib/mocha.cjs","lineNumber":490,"sourceCode":"\n/**\n * Unloads `files` from Node's `require` cache.\n *\n * @description\n * This allows required files to be \"freshly\" reloaded, providing the ability\n * to reuse a Mocha instance programmatically.\n * Note: does not clear ESM module files from the cache\n *\n * <strong>Intended for consumers &mdash; not used internally</strong>\n *\n * @public\n * @see {@link Mocha#run}\n * @returns {Mocha} this\n * @chainable\n */\nMocha.prototype.unloadFiles = function () {\n  if (this._state === mochaStates.DISPOSED) {\n    throw createMochaInstanceAlreadyDisposedError(\n      \"Mocha instance is already disposed, it cannot be used again.\",\n      this._cleanReferencesAfterRun,\n      this,\n    );\n  }\n\n  this.files.forEach(function (file) {\n    Mocha.unloadFile(file);\n  });\n  this._state = mochaStates.INIT;\n  return this;\n};\n\n/**\n * Sets `grep` filter after escaping RegExp special characters.\n *\n * @public\n * @see {@link Mocha#grep}","sourceCodeStart":472,"sourceCodeEnd":508,"githubUrl":"https://github.com/mochajs/mocha/blob/6bcbee4fd9a95351cedf0fdcb14c7d696486bc5a/lib/mocha.cjs#L472-L508","documentation":"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.","triggerScenarios":"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.","commonSituations":"Programmatic usage that reuses one Mocha instance across multiple runs after calling dispose(); test runners/IDE integrations holding a disposed instance; calling unloadFiles() twice.","solutions":["Create a new Mocha instance instead of reusing the disposed one","Set cleanReferencesAfterRun: false in options if you intentionally want to reuse one instance across runs","Guard with a state check or a try/catch before reusing an instance you may have disposed"],"exampleFix":"// before\nconst mocha = new Mocha();\nawait runOnce(mocha);\nmocha.dispose();\nmocha.unloadFiles(); // throws\n// after\nconst mocha = new Mocha();\nawait runOnce(mocha);\nmocha.dispose();\nconst mocha2 = new Mocha(); // fresh instance for further use\nmocha2.unloadFiles();","handlingStrategy":"try-catch","validationCode":"// check state before use\nif (mocha._state === 'disposed' || mocha._state === 'references-cleaned') {\n  mocha = new Mocha(options);\n}","typeGuard":"function isUsable(mocha) {\n  return mocha && mocha._state !== 'disposed' && mocha._state !== 'references-cleaned';\n}","tryCatchPattern":"try {\n  mocha.unloadFiles();\n} catch (err) {\n  if (err.code === 'ERR_MOCHA_INSTANCE_ALREADY_DISPOSED') {\n    mocha = new Mocha(options);\n  } else {\n    throw err;\n  }\n}","preventionTips":["Treat one Mocha instance as single-run; create a new one per run","Set cleanReferencesAfterRun: false only when reuse is intentional","Keep a single owner of instance lifecycle to avoid stray dispose() calls"],"tags":["mocha","instance-lifecycle","programmatic-api","state-error"],"backgroundTag":"mocha-instance-disposed","analyzedSha":"6bcbee4fd9a95351cedf0fdcb14c7d696486bc5a","analyzedAt":"2026-09-01T03:41:47.182Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}