ReferenceError: x is not defined

Node.js · updated 2026-11-02

Thrown when code reads a name that was never declared in any scope it can see. The message names it, so ReferenceError: __dirname is not defined points at one identifier. In production it often appears only on one code path, or only after a build or runtime change, because that is the first time the line runs in that environment.

ReferenceError: __dirname is not defined in ES module scope
    at file:///srv/app/server.js:7:30
    at ModuleJob.run (node:internal/modules/esm/module_job:271:25)

Quick fix

Find where the name was supposed to come from. If it is your own function or variable, add the missing import or declaration. If it is a global from another environment (window, document, require, __dirname, __filename), use the equivalent that exists where the code runs: in ES modules use import.meta.dirname / import.meta.filename or new URL(..., import.meta.url), and import instead of require.

Read the exact name in the message.
Search the file for an import, require or declaration of that name; a refactor often removes one but keeps a use.
Check the module type: "type": "module" in package.json or a .mjs file makes __dirname, __filename and require undefined.
For browser globals (window, document, localStorage) in server code, move the code behind a check or into code that only runs in the browser.
Check spelling and case: userId and userID are different names.

javascript

// ES module replacements for CommonJS globals
import path from "node:path";
import { createRequire } from "node:module";

const __dirname = import.meta.dirname;            // Node 20.11+ / 21.2+
const configPath = path.join(__dirname, "config.json");

const require = createRequire(import.meta.url);   // only if you must load a CommonJS module

Why it happens

Missing import after a refactor

A helper moved to another file and one caller kept using it without importing it. Bundlers and TypeScript usually catch this, but plain JavaScript only fails when that line runs.

CommonJS globals in an ES module

__dirname, __filename, require, module and exports exist only in CommonJS. Switching package.json to "type": "module" or renaming a file to .mjs turns every use into a ReferenceError.

Browser globals in server code

window, document and localStorage exist in browsers, not in Node. Server-side rendering runs shared component code on the server first, where these are undefined.

A typo or different case

JavaScript names are case-sensitive, so a misspelled or differently-cased name is simply undeclared.

A variable declared in a narrower scope

A const or let declared inside an if block or a function is not visible outside it. Moving a line out of the block leaves it pointing at nothing.

Other fixes

Turn on no-undef in ESLint (or type-check with TypeScript) so undeclared names fail in CI instead of in production.
For shared server and browser code, check typeof window !== 'undefined' before touching browser globals.
Keep one module system per package; mixing require and import is a common source of both this and ERR_REQUIRE_ESM.

Same error, other wording

ReferenceError: require is not defined in ES module scope, you can use import instead
ReferenceError: window is not defined
ReferenceError: fetch is not defined

Let your coding agent catch the next one

Runheed records this error in production with the stack trace, the breadcrumbs before it and the agent session that shipped the code, and serves it to Claude Code, Cursor or any MCP client. With it connected, you can ask:

> Find the ReferenceError exceptions in production, show the stack trace and the release behind the latest one, work out whether the name is a missing import, a CommonJS or browser global, or a typo, and fix it where it is used.

Plans from $29/mo See what your agent reads See the setupCancel any time from the billing portal