{"record":{"id":"b4cb55b2163efaa5","repo":"mochajs/mocha","slug":"err-mocha-unsupported-b4cb55","errorCode":"ERR_MOCHA_UNSUPPORTED","errorMessage":"unloadFile() is only supported in a Node.js environment","messagePattern":"unloadFile\\(\\) is only supported in a Node\\.js environment","errorType":"exception","errorClass":"UnsupportedError","httpStatus":null,"severity":"error","filePath":"lib/mocha.cjs","lineNumber":466,"sourceCode":"    function (file, resultModule) {\n      suite.emit(EVENT_FILE_REQUIRE, resultModule, file, self);\n      suite.emit(EVENT_FILE_POST_REQUIRE, global, file, self);\n    },\n    esmDecorator,\n  );\n};\n\n/**\n * Removes a previously loaded file from Node's `require` cache.\n *\n * @private\n * @static\n * @see {@link Mocha#unloadFiles}\n * @param {string} file - Pathname of file to be unloaded.\n */\nMocha.unloadFile = function (file) {\n  if (utils.isBrowser()) {\n    throw createUnsupportedError(\n      \"unloadFile() is only supported in a Node.js environment\",\n    );\n  }\n  return require(\"./nodejs/file-unloader.cjs\").unloadFile(file);\n};\n\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}","sourceCodeStart":448,"sourceCodeEnd":484,"githubUrl":"https://github.com/mochajs/mocha/blob/6bcbee4fd9a95351cedf0fdcb14c7d696486bc5a/lib/mocha.cjs#L448-L484","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Only call unloadFile/unloadFiles in Node; guard with a Node environment check before calling","Skip the unload step in browser builds (browser Mocha has no require cache to clear)","If unloading is needed for watch mode, ensure that code path runs only in the Node CLI, not the browser bundle"],"exampleFix":"// before\nMocha.unloadFile(file);\n// after\nif (!utils.isBrowser()) {\n  Mocha.unloadFile(file);\n}","handlingStrategy":"type-guard","validationCode":"if (typeof process === 'undefined' || typeof require === 'undefined') {\n  // browser: do not call unloadFile/unloadFiles\n}","typeGuard":"function isNode() {\n  return (\n    typeof process !== 'undefined' &&\n    process.versions != null &&\n    process.versions.node != null\n  );\n}\nif (isNode()) Mocha.unloadFile(file);","tryCatchPattern":"try {\n  Mocha.unloadFile(file);\n} catch (err) {\n  if (err.code === 'ERR_MOCHA_UNSUPPORTED') {\n    // browser environment: skip unloading\n  } else throw err;\n}","preventionTips":["Gate unloadFiles/watch logic behind a Node environment check","Keep browser test harness code free of Node-only Mocha statics","Avoid bundling node-only Mocha modules into browser builds","Document that module-cache unloading is a Node-only capability"],"tags":["browser","node-only","api-misuse"],"backgroundTag":"browser-only-api-in-node","analyzedSha":"6bcbee4fd9a95351cedf0fdcb14c7d696486bc5a","analyzedAt":"2026-09-01T03:41:47.182Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}