Debugging JavaScript

Reading error messages, using browser DevTools, breakpoints, console methods, and systematic debugging techniques.

What it is, in plain English: Debugging is the process of finding and fixing errors in code. JavaScript gives you two main environments to debug in: the browser DevTools (Sources tab, Console, Network, Performance) and the Node.js debugger (via --inspect or VS Code). The most important skill is reading the error message and stack trace correctly — they tell you exactly where the problem is.

Reading errors and using the console

Step 1: Read the error message

// Every JavaScript error tells you three things:
// 1. The ERROR TYPE
// 2. The MESSAGE (what went wrong)
// 3. The STACK TRACE (where in your code it happened)

// Example error:
// TypeError: Cannot read properties of undefined (reading 'name')
//   at getUsername (app.js:15:22)
//   at handleLogin (app.js:8:18)
//   at HTMLButtonElement.onclick (index.html:23)

// Reading it:
// TypeError     — type of error (wrong type being used)
// "reading 'name'" — you tried to access .name on something undefined
// app.js:15:22  — line 15, column 22 of app.js ← GO HERE FIRST
// The rest shows what called what (call stack, bottom-to-top = oldest to newest call)

Common errors and what they mean

// TypeError — wrong type
// "Cannot read properties of null (reading 'X')" → something is null
// "X is not a function" → you're calling something that isn't a function
// "Cannot set properties of undefined" → parent object doesn't exist

// ReferenceError — variable doesn't exist
// "X is not defined" → you used a variable before declaring it, or misspelled it

// SyntaxError — invalid code
// "Unexpected token" → missing bracket, comma, or typo in the code itself

// RangeError — value out of valid range
// "Maximum call stack size exceeded" → infinite recursion!

// Solving them:
const user = null;
// user.name  → TypeError: Cannot read properties of null
const safeName = user?.name ?? "Anonymous";  // fix: use optional chaining

console methods beyond console.log

// Different severity levels (show differently in DevTools):
console.log("info message");
console.warn("warning — check this");   // yellow in DevTools
console.error("error — something wrong"); // red, includes stack trace

// console.table — perfect for arrays of objects:
console.table([
  { name: "Alice", score: 95 },
  { name: "Bob",   score: 87 },
]);

// console.group — organise related logs:
console.group("Checkout process");
  console.log("Cart validated");
  console.log("Payment processed");
  console.log("Email sent");
console.groupEnd();

// console.time — measure how long something takes:
console.time("my operation");
// ... code ...
console.timeEnd("my operation");  // "my operation: 12.3ms"

Using browser DevTools (the most powerful tool)

// Open DevTools: F12 or Ctrl+Shift+I (Cmd+Option+I on Mac)

// Console tab:
//   - See all errors (red), warnings (yellow), logs
//   - Type JS directly — access your page's variables and functions
//   - Click the filename in errors to jump to the code

// Sources tab — the debugger:
//   - Find your JS file, click a line number to add a BREAKPOINT
//   - Reload the page — execution stops at your breakpoint
//   - Inspect all variable values at that moment
//   - Step through code line by line with F10 (step over) or F11 (step into)

// Network tab:
//   - See all HTTP requests your page makes
//   - Check status codes, request/response bodies
//   - Perfect for debugging fetch() calls

// The 'debugger' statement — set a breakpoint from code:
function processOrder(order) {
  debugger;  // DevTools will pause here (only when DevTools is open)
  return order.items.reduce((sum, item) => sum + item.price, 0);
}

Try It Yourself

// All the console methods you should know
console.log("Basic output:", 42, [1,2,3], {a:1});

// Styled output (browser):
console.log("%cImportant message", "color: red; font-size: 16px; font-weight: bold");

// Groups — collapse related logs:
console.group("User processing");
  console.log("Validating...");
  console.log("Saving...");
  console.warn("Email not verified");
console.groupEnd();

// Table — perfect for arrays of objects:
const users = [
  { name: "Alice", age: 30, role: "admin" },
  { name: "Bob",   age: 25, role: "user" },
  { name: "Carol", age: 35, role: "user" },
];
console.table(users);

// Timing — measure performance:
console.time("array sort");
const arr = Array.from({ length: 100000 }, () => Math.random());
arr.sort((a, b) => a - b);
console.timeEnd("array sort");  // "array sort: 8.2ms"

// Count — how many times a code path runs:
for (let i = 0; i < 5; i++) {
  if (i % 2 === 0) console.count("even");
  else             console.count("odd");
}

// Assert — only logs if condition is FALSE:
console.assert(2 + 2 === 4, "Math is broken");  // nothing
console.assert(2 + 2 === 5, "This fails");       // logs error

// Trace — where was this function called from?
function innerFn() { console.trace("where am I called from?"); }
function outerFn() { innerFn(); }
outerFn();  // shows the call stack

Systematic debugging and Node.js

The scientific method for debugging

// 1. REPRODUCE — make the bug happen reliably
//    What exact steps cause it? Can you write a failing test?

// 2. ISOLATE — narrow it down
//    Binary search: comment out half the code. Still broken? The bug is in the remaining half.
//    Add console.logs before and after suspected code:
function suspectFunction(data) {
  console.log("Input:", data);          // what came in?
  const result = transform(data);
  console.log("After transform:", result); // what's intermediate state?
  const final = format(result);
  console.log("Output:", final);        // what went out?
  return final;
}

// 3. UNDERSTAND — WHY is it broken? (don't guess — know)
// 4. FIX — minimal change that addresses the root cause
// 5. VERIFY — run the test, check edge cases, make sure nothing else broke

Debugging async code

// Async errors often have useless stack traces.
// Always wrap async code in try/catch with meaningful error messages:
async function loadUserData(userId) {
  try {
    const user = await fetchUser(userId);
    const posts = await fetchPosts(userId);
    return { user, posts };
  } catch (e) {
    // Add context to the error before re-throwing:
    throw new Error(`Failed to load user ${userId}: ${e.message}`, { cause: e });
  }
}

// Unhandled promise rejections — always handle them:
window.addEventListener("unhandledrejection", (event) => {
  console.error("Unhandled rejection:", event.reason);
  event.preventDefault();  // prevent the default browser behaviour
});

Node.js debugging

// Method 1: --inspect flag (Chrome DevTools for Node):
// node --inspect server.mjs
// Open chrome://inspect in Chrome → click "inspect"

// Method 2: VS Code built-in debugger (best for projects):
// .vscode/launch.json:
// {
//   "type": "node",
//   "request": "launch",
//   "name": "Debug server",
//   "program": "\${workspaceFolder}/server.mjs",
//   "runtimeArgs": ["--experimental-vm-modules"]
// }

// Method 3: node --inspect-brk (break on first line):
// node --inspect-brk server.mjs  ← stops at line 1 so you can set breakpoints

// Debugging with util.inspect (better than console.log for deep objects):
import { inspect } from "util";
console.log(inspect(deepObject, { depth: null, colors: true }));

Performance profiling and memory debugging

Profiling CPU performance

// Browser: Performance tab → Record → run your operation → Stop
// Gives a flame chart showing which functions took the most time.

// Code-level:
console.time("expensive operation");
heavyComputation();
console.timeEnd("expensive operation");

// More precise (sub-millisecond):
const t0 = performance.now();
heavyComputation();
const t1 = performance.now();
console.log(`Took ${(t1 - t0).toFixed(3)}ms`);

// Performance marks/measures (appear in DevTools timeline):
performance.mark("start-fetch");
await fetchData();
performance.mark("end-fetch");
performance.measure("fetch duration", "start-fetch", "end-fetch");
console.log(performance.getEntriesByName("fetch duration"));

Finding memory leaks

// Common memory leak sources:
// 1. Event listeners not removed:
element.addEventListener("click", handler);
// Fix: element.removeEventListener("click", handler) in cleanup

// 2. Closures holding large objects:
function createLeak() {
  const bigData = new Array(1000000).fill("x");
  return () => bigData[0];  // closure keeps bigData alive!
}

// 3. Global variables accumulating:
window.users = [];
// Fix: use let/const in function scope

// Detecting leaks: Browser DevTools → Memory tab
// → Take heap snapshot → Perform operation → Take another snapshot
// → Compare: what objects grew?

// In Node.js:
process.memoryUsage();
// { rss, heapTotal, heapUsed, external, arrayBuffers }

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.