Advanced debugging

Advanced debugging means asking smaller questions

You already know the basics from Debugging in the browser. You can set a breakpoint: a mark on a line that makes the code stop there, so you can look around. You can step through code one line at a time, and you can read the values of variables.

You also learned in Reading error messages that the top line of a stack trace shows where an error was thrown. That is a clue, not always the cause. This lesson builds on those skills.

The tools in this lesson do more than a plain breakpoint. Here is the list. Each one is explained when it comes up:

• breakpoints that stop only when a condition is true;
• logpoints, which print a message without stopping;
• breakpoints that stop when the page changes, an event fires, or a request starts;
• a setting that stops the code when an error is thrown;
• the Ignore List, which skips code you didn't write;
• stack traces for async code;
• source maps, and the Node.js debugger.

The skill is to pick the smallest tool that answers your current question.

This lesson uses ideas from try/catch, custom errors, async/await, promise errors, bundlers and source maps, and JavaScript runtimes.

A tool only helps when you can make the bug happen again and again. So start with a simple method, and repeat it until the bug is fixed:

1. Make the bug happen.
2. Shrink the code until only the failing part is left.
3. Make one guess about the cause.
4. Check that guess by looking at real values.
5. Fix the smallest line, then run everything again.

function totalAfterDiscount(price, discount) {
  return price - discount;
}
console.log(totalAfterDiscount(20, 10));

Line 4 calls the function with a price of 20 and a discount of 10 percent. Line 2 takes away 10 as if it were 10 dollars, not 10 percent. So line 4 prints 10. The right answer is 18.

This tiny program has no page, no buttons, and no network. It still shows the bug. So the bug must be in the formula on line 2. A small program like this is called a minimal reproduction: the least code that still makes the bug happen.

function totalAfterDiscount(price, discount) {
  return price * (1 - discount / 100);
}
console.log(totalAfterDiscount(20, 10));

On line 2, discount / 100 turns 10 percent into 0.1. Then 1 - 0.1 is 0.9, and 20 times 0.9 is 18. So line 4 prints 18. Keep the same inputs, 20 and 10, when you test the fix. With new inputs, you can't tell whether the fix worked.

Sometimes the code worked last week, and now it doesn't. Somewhere in a list of changes, one change broke it. You can find that change fast with bisecting, which means cutting the list in half again and again:

• Test the app with the changes up to the middle of the list.
• If the test fails, the bad change is in the first half. Keep that half.
• If the test passes, the bad change is in the second half. Keep that half.
• Repeat until one change is left.

One more trick: explain the code out loud, line by line, to a friend or even to a toy duck. This is called rubber-ducking. When you say each value out loud, you often notice the one you never checked.

1const changes = [2  { id: "a-route", label: "add account route" },3  { id: "b-layout", label: "move checkout layout" },4  { id: "c-copy", label: "rewrite button copy" },5  { id: "discount-formula", label: "replace discount formula" },6  { id: "e-theme", label: "adjust theme tokens" },7  { id: "receipt-cache", label: "cache receipt payload" },8];9 10function testUpTo(index) {11  return changes.slice(0, index + 1).some(change => change.id === "discount-formula")12    ? "fail"13    : "pass";14}15 16function bisectFirstBad() {17  let low = 0;18  let high = changes.length - 1;19  const steps = [];20  while (low < high) {21    const mid = Math.floor((low + high) / 2);22    const result = testUpTo(mid);23    steps.push(`test through ${changes[mid].id}: ${result}`);24    if (result === "fail") high = mid;25    else low = mid + 1;26  }27  return { first: changes[low], steps };28}29 30const report = bisectFirstBad();31console.log(report.first.label);32console.log(report.steps.join(" | "));

In a real project, git bisect does this search for you. Git is the tool that keeps the history of your code, and a commit is one saved change in that history. You tell git one commit that works and one that fails. Git then picks commits in between, and you run the same test on each one.

Use a test that gives the same result every time. If the test sometimes passes and sometimes fails, the search gives a wrong answer. When you are done, git bisect reset takes you back to the code you started with. Type these commands in a terminal, not in the editor.

# In a clean working tree, replace GOOD_SHA with a commit known to pass.
git bisect start
git bisect bad HEAD
git bisect good GOOD_SHA
# Run the same checkout test at each checked-out commit.
git bisect good  # test passes; otherwise use git bisect bad
git bisect reset # return to the original branch when finished

A plain breakpoint stops every time its line runs. In a loop over 500 items, that is 500 stops. Two tools help:

• A conditional breakpoint stops only when a condition you type is true.
• A logpoint prints a message to the Console each time the line runs, and never stops.

In Chrome DevTools, open the Sources panel. Right-click a line number. Then choose Add conditional breakpoint... or Add logpoint.... Firefox uses the same names.

const cart = [{ id: 17 }, { id: 42 }];
for (const item of cart) {
  if (item.id === 42) console.log(item.id);
}

The loop visits both items. The condition on line 3 is false for 17 and true for 42. So the program prints 42 once.

In DevTools you can ask the same question without editing the code. Put a conditional breakpoint on line 3 with the condition item.id === 42. The code stops only for that item. This snippet only acts out the condition; running it doesn't create a breakpoint.

const cart = [{ id: 17 }, { id: 42 }];
for (const item of cart) {
  console.log("checking", item.id);
}

Here line 3 prints checking 17, then checking 42. A logpoint gives you the same two lines without editing the file. Its message would be "checking", item.id. The message is real JavaScript, so it runs each time. Don't put code in it that changes values, and don't print private data.

DevTools has more kinds of breakpoints. The comments below list the names to look for in Chrome. They are not code you can run.

1// Chrome DevTools Sources panel names to look for:2// Add conditional breakpoint...    item.id === 423// Add logpoint...                  "item", item.id, item.stock4// DOM breakpoints                  subtree modifications, attribute modifications, node removal5// Event Listener Breakpoints       click, input, timer, animation, and more6// XHR/fetch Breakpoints            pause when the request URL contains text7// Pause on exceptions              uncaught only, or caught and uncaught8// Ignore List                      skip framework or extension scripts while stepping

A condition runs where the line is, so it can use the variables there, like item. You can also count calls. Say a bug happens on the third click. Put a conditional breakpoint on the line that adds 1 to the count, with the condition clickCount === 2. The count is still 2 when the third click reaches that line, so the code stops on the third click.

A logpoint prints without stopping. That matters when stopping would change what you are looking at, like a timer or an animation.

Some bugs aren't about one line. These breakpoints stop the code when something happens on the page:

• DOM breakpoint. The DOM is the page's tree of elements. If a pop-up box vanishes, right-click it in the Elements panel. Choose Break on, then Node removal. The code stops on the line that removes it. If the box is replaced instead, choose Subtree modifications on its parent.
• Event listener breakpoint. If you don't know which function handles a click, open Sources, then Event Listener Breakpoints, and tick click. The code stops inside the function when a click happens.
• XHR/fetch breakpoint. If the checkout sends a request to the wrong address, open Sources, then XHR/fetch Breakpoints, and add /checkout. The code stops when a request whose address contains that text starts. It looks only at the address, not at the answer from the server.

1const items = [Run2  { id: 17, label: "keyboard", stock: 4 },3  { id: 42, label: "monitor", stock: -1 },4  { id: 58, label: "dock", stock: 3 },5];6 7function firstBrokenItem(items, breakWhen) {8  const log = [];9  for (const item of items) {10    log.push(`checking ${item.id}`);11    if (breakWhen(item)) {12      return { item, log };13    }14  }15  return { item: null, log };16}17 18const result = firstBrokenItem(items, item => item.id === 42);19console.log(result.item.id);20console.log(result.log.join(" -> "));

1const items = [2  { id: 17, label: "keyboard", stock: 4 },3  { id: 42, label: "monitor", stock: -1 },4  { id: 58, label: "dock", stock: 3 },5];6 7function firstBrokenItem(items, breakWhen) {8  const log = [];9  for (const item of items) {10    log.push(`checking ${item.id}`);11    if (breakWhen(item)) {12      return { item, log };13    }14  }15  return { item: null, log };16}17 18const result = firstBrokenItem(items, item => item.id === 42);19console.log(result.item.id);20console.log(result.log.join(" -> "));

A logpoint sits between console.log and a breakpoint. It gives you a clue, and the program keeps running. The tool below is not DevTools. It is a small function that acts like a logpoint: it prints only when a condition is true, and it doesn't change what the code does.

1function withConditionalTrace(fn, shouldLog) {2  return (...args) => {3    const result = fn(...args);4    if (shouldLog(args, result)) {5      console.log(`${fn.name}(${args.join(", ")}) -> ${result}`);6    }7    return result;8  };9}10 11const priceWithTax = (price, rate) => Number((price * (1 + rate)).toFixed(2));12const tracedPrice = withConditionalTrace(priceWithTax, (args, result) => result > 50);13console.log(tracedPrice(20, 0.1));14console.log(tracedPrice(60, 0.1));

The table below compares four ways to look inside running code. Read each row as: "use this tool when..., and watch out for...".

A stack trace is the list of function calls that were running when an error happened. Each line is one call.

Async code makes this harder. When a function hits await, it pauses. Later it starts again, but by then the functions that called it have stopped running. Older engines lost those callers. Their stack traces ended at the await.

V8 is the JavaScript engine inside Chrome and Node. Modern V8 remembers which function was waiting with await for which. So its stack traces can show lines like at async outer under the function that threw.

async function loadCart() {
  throw new Error("cart unavailable");
}
loadCart().catch(error => console.log(error.message));

Line 2 throws inside an async function, so the promise it returns is rejected. The .catch on line 4 prints cart unavailable. Without the .catch, the error would stay inside a rejected promise.

To see the stack, keep the error object itself. Don't replace it with a new message. The next example does that.

1Error.stackTraceLimit = 20;2 3async function leaf() {4  await Promise.resolve();5  throw new Error("boom from leaf");6}7 8async function middle() {9  await leaf();10}11 12async function outer() {13  await middle();14}15 16outer().catch(error => {17  console.log(error.stack.split("\n").slice(0, 5).join("\n"));18});

Line 1 asks V8 to keep up to 20 lines of stack. Lines 3 to 14 build a chain: outer waits for middle, and middle waits for leaf. Line 5 throws after an await. Line 17 prints the first five lines of the stack.

Stack traces are text, and each engine writes them its own way. V8 writes lines like at async outer (file.js:12:3). Firefox often writes outer@file.js:12:3. So read a stack trace as a clue for people, not as data your code depends on.

The DevTools Call Stack panel can show even more. It can link a callback to the code that scheduled it. The error.stack text only shows what the engine saved. Some timers and callbacks don't remember who created them. When that link is missing, keep the original error as a cause, or print a stack where the work is scheduled.

1function createInputError(message) {2  const error = new Error(message);3  Error.captureStackTrace?.(error, createInputError);4  return error;5}6 7function validateCart() {8  return createInputError("missing total");9}10 11console.log(validateCart().stack);

Error.captureStackTrace only exists in V8. It rebuilds an error's stack and leaves out the function you pass, plus everything above it. On line 3, that is createInputError. So the stack starts at validateCart, the code that asked for the error.

The ?. on line 3 is optional chaining: if captureStackTrace doesn't exist, as in Firefox, the call is skipped. The error still works without it.

1const networkError = new Error("request failed");2const checkoutError = new Error("checkout failed", { cause: networkError });3 4console.log(checkoutError.message);5console.log(checkoutError.cause.message);

Line 2 makes a new error and passes the first one as cause. Line 4 prints checkout failed. Line 5 prints request failed. Both messages stay, and neither is mixed into the other.

Two more tools help here:

• console.trace() prints the current stack without throwing an error.
• Error.stackTraceLimit sets how many lines of stack V8 keeps.

Use them while you debug. Don't build your program's logic on them.

1function leaf() {2  console.trace("discount path");3}4 5function outer() {6  leaf();7}8 9outer();

The code a browser runs is often not the code you wrote. Build tools change it first:

• they turn TypeScript into JavaScript;
• they join many files into one;
• they minify it, which means they remove spaces and shorten names to make the file smaller.

The new file is called generated code. A source map is a separate file that links each line of generated code back to the line you wrote. With it, DevTools can show your own file and let you put breakpoints in it.

function checkout(total) {
  throw new Error("bad total: " + total);
}
try { checkout(0); } catch (error) { console.log(error.message); }

Line 2 throws, and the catch on line 4 prints bad total: 0. A source map would not change this message. It also would not change how the code runs. It only changes which file and line a stack trace points to.

If DevTools still shows the generated file, check two things. Does the map file load? Was it made by the same build as the code?

1export function originalName(total: number) {2  throw new Error("mapped failure for " + total);3}4 5originalName(42);

1export function originalName(total) {2  throw new Error("mapped failure for " + total);3}4originalName(42);5//# sourceMappingURL=checkout.js.map

Line 5 of the generated file is a comment: //# sourceMappingURL=checkout.js.map. It tells DevTools or Node where to find the map. The throw is on line 2 in both files, so the map leads from line 2 of the JavaScript to line 2 of the TypeScript.

In Chrome you can turn source maps on or off. Open Settings, then Preferences, then Sources, and find Enable JavaScript source maps.

Chrome also has an Ignore List. Files on it, like library or framework code, are skipped when you step through code. Older tools called this blackboxing, and Firefox still uses that word.

The table below shows where source maps are used. Read each row as: "in this place, the map does this, and here is a good habit".

1# Browser builds usually attach a comment near the end of the file:2# //# sourceMappingURL=checkout.js.map3 4# Node can remap stack traces when the .js file and .map file are present:5node --enable-source-maps dist/checkout.js6 7# Many production web builds keep maps private instead:8# use a hidden-source-map setting, upload the .map files to your error tracker,9# and do not publish sourceMappingURL comments for users to download.

Node has a built-in debugger connection called the inspector. Chrome DevTools can connect to it. Here is how:

1. Start your program with node --inspect.
2. In Chrome, open chrome://inspect.
3. Click your program to connect DevTools to it.

If the bug happens while the program is starting, use --inspect-brk instead. It stops before the first line of your code runs, so you have time to connect.

1# Start Node with the inspector and attach Chrome DevTools from chrome://inspect.2node --inspect server.js3node --inspect-brk server.js4 5# Debug the built-in test runner before the first line runs.6node --test --inspect-brk tests/checkout.test.mjs7 8# Use the terminal debugger when you only have a shell.9node inspect server.js

There are other ways to debug Node:

• VS Code's JavaScript Debug Terminal starts every Node program in it with the debugger on.
• A launch.json file saves your debug settings, so the whole team starts the program the same way.
• node inspect is a debugger that works right in the terminal.
• node --test --inspect-brk stops Node's built-in test runner before the test file runs.

1const util = require("node:util");2console.log(util.inspect({ cart: { total: 18 } }, { depth: 2 }));3 4process.on('uncaughtException', (error) => {5  console.error(error);6  process.exitCode = 1;7});8 9process.on('unhandledRejection', (reason) => {10  console.error(reason);11  process.exitCode = 1;12});

Lines 1 and 2 print an object with util.inspect(value, { depth: 2 }). The depth sets how many levels of nested objects to show.

Lines 4 to 12 listen for two events. uncaughtException fires when an error is never caught. unhandledRejection fires when a rejected promise has no .catch. These handlers are a last chance to report the problem. Log the error, set the exit code to 1 so the program counts as failed, and then fix the code that threw. Don't act as if everything is fine.

You can also run a program with NODE_DEBUG=http,net in front of the command. Node then prints its own notes about those built-in parts, here web requests and network connections.

Never open the inspector to the internet. Anyone who connects to it can run any code inside your program. Keep it on your own computer, and use a protected connection to debug a remote server.

Here are three bugs you will meet in real apps, and the tool that fits each one first:

• A bug that happens only on the third click: a conditional breakpoint on the line that adds 1 to the count.
• A click handler you can't find: an event listener breakpoint.
• A wrong value in a loop: a condition like item.id === 42, or a logpoint.
• An error that a catch hides: stop on caught errors, read the async stack, and keep the cause.

1let clickCount = 0;Run2let submitted = false;3 4function handleCheckoutClick() {5  clickCount += 1;6  if (clickCount === 3) {7    submitted = true;8    return "submitted twice";9  }10  return "waiting";11}12 13console.log(handleCheckoutClick());14console.log(handleCheckoutClick());15console.log(handleCheckoutClick());

The Console has three more tools for quick checks:

• console.table shows a list of objects as a table with rows and columns.
• console.time starts a timer, and console.timeEnd stops it and prints how long it took.
• console.assert prints a message when something you expected is false. It doesn't stop the program.

const cart = [{ item: "tea", stock: 0 }, { item: "milk", stock: 2 }];
console.table(cart);
console.log(cart.find(row => row.stock === 0).item);

Line 1 makes two rows. Line 2 shows them as a table, with an item column and a stock column. Line 3 finds the row with no stock and prints tea. Don't print customers' private details to a Console that other people can see.

console.time("cart check");
const cart = ["tea", "milk"];
console.log(cart.includes("tea"));
console.timeEnd("cart check");

Lines 1 and 4 use the same label, "cart check", so they belong to the same timer. Line 3 prints true. The time printed by line 4 is different on every run, so don't treat it as an exact speed test. Give each timer its own label when two run at the same time.

const cart = { stock: 0 };
console.assert(cart.stock > 0, "tea is out of stock");
console.log("checkout continues");

Stock is 0, so cart.stock > 0 is false. Line 2 prints Assertion failed: tea is out of stock. Then line 3 still runs and prints checkout continues. When a failure must stop the program, throw an error or use a test instead.

Now the hidden error. A catch block that hides an error is said to swallow it. The code below swallows one.

1async function saveOrder() {2  throw new Error("network down");3}4 5async function checkout() {6  try {7    await saveOrder();8    return "saved";9  } catch (error) {10    return "saved"; // bug: the rejection was swallowed11  }12}13 14checkout().then(status => console.log(status));

Line 2 throws network down. Line 9 catches it. Then line 10 returns "saved" anyway. So line 14 prints saved, even though nothing was saved.

To find a bug like this, turn on Pause on caught exceptions in DevTools. The code then stops on line 2, where the error is thrown, even though a catch handles it later. Then fix the catch so callers learn about the failure and the original error stays attached.

1async function saveOrder() {2  throw new Error("network down");3}4 5async function checkout() {6  try {7    await saveOrder();8    return { ok: true };9  } catch (error) {10    throw new Error("checkout failed", { cause: error });11  }12}13 14checkout().catch(error => console.log(error.cause.message));

Now line 10 throws a new error with the original as its cause. The .catch on line 14 reads error.cause.message and prints network down.

1function submitForm(form) {2  // Temporary local-only pause. Remove it before sharing code.3  debugger;4  return form.checkValidity();5}

The debugger; statement on line 3 works like a breakpoint written in the code. It stops the code only when DevTools or another debugger is open. Otherwise the function runs as usual. It helps when you can't easily click on the right line, as in generated files. Remove it before you share your code.

Common misconceptions

The table below lists three pairs of ideas that are easy to mix up. Read each row as: "these two get mixed up, here is the difference, and here is what to do".

Some questions ask which tool to use. Others ask what code prints. For code, follow the values line by line.

Key takeaways

• Start with the method: make the bug happen, shrink it, guess one cause, and check it. Tools come after.
• Each kind of breakpoint answers a different question: a condition, a logpoint, a page change, an event, a request, or a thrown error.
• Modern stack traces can follow await chains, but each engine writes them its own way.
• Source maps lead from the code that runs back to the code you wrote. Keep them private when your code is private.
• For Node, use --inspect, VS Code, node inspect, or NODE_DEBUG, and treat last-chance error handlers as reports, not fixes.

Up next: Creational patterns.