ReferenceError: X is not defined — What It Means and How to Fix It

ReferenceError: X is not defined means JavaScript cannot find a variable or function named X in the current scope. This is a runtime error that stops execution immediately.

What "ReferenceError: X is not defined" Means

JavaScript throws this error when your code tries to access a variable, function, or identifier that doesn't exist in the current execution context. The engine looks through all scopes (local, closure, global) and finds nothing named X. Unlike undefined (which means the variable exists but has no value), this error means the identifier itself is missing.

Why It Happens

The most common causes, in order of frequency:

1. Misspelled variable names — you declared userName but typed username later.
2. Scope issues — you're referencing a variable outside the block or function where it was declared.
3. Load order problems — you're calling a function before its script file has executed (common in browser <script> tags).

Example Code That Triggers It

Here's a minimal, runnable example that throws this exact error in Node.js or any browser console:

function calculateTotal(price, quantity) {
  return price * quantity;
}

console.log(calculateTotal(10, 2)); // Works fine: 20
console.log(calculateTotal(10, qty)); // ReferenceError: qty is not defined

Run this in Node.js (node script.js) or paste it into your browser's DevTools console. The second console.log throws because qty was never declared — there's no variable with that name anywhere in the program.

How to Fix It

Declare the variable before using it, and make sure the spelling matches exactly:

function calculateTotal(price, quantity) {
  return price * quantity;
}

const qty = 2; // Declare it first
console.log(calculateTotal(10, 2)); // Works fine: 20
console.log(calculateTotal(10, qty)); // Works fine: 20

The fix works because qty now exists in the global scope, so JavaScript can resolve it when the function call executes.

Common Mistakes That Cause This

Two mistakes I see developers repeat:

1. Using a variable inside a block before it's declared with let or const — even though var hoists (making it undefined), let and const throw a ReferenceError if accessed before the declaration line runs.

2. Forgetting to import or require a module — in Node.js, using fs.readFile() without const fs = require('fs') at the top gives you ReferenceError: fs is not defined. Same with ES modules: import { readFile } from 'fs' is required first.

When Should You Worry About This?

You should worry when this error appears in production code, not just during development. In a browser, it means a script failed to load or execute in order — check your <script> tags and ensure dependencies load first. In Node.js, it often signals a circular dependency where two modules reference each other before either finishes initializing. If it happens in a Next.js server component, check that you're not referencing client-only variables (like window) server-side.

Next time you see this, check your spelling first — 9 times out of 10, userName and username are the culprit.