Debugging: breakpoints, console and reading a stack trace

The most expensive beginner habit is changing code at random until the error goes away. Sometimes it does, but the cause stays and comes back elsewhere. Debugging is a short four-step loop that works in any language.

Let's run the loop on a teaching program: it totals a coffee shop order with delivery and a promo code. It has three deliberate bugs of different kinds: a crash with an exception, a wrong result caused by types, and a condition that never fires.

export function calcSubtotal(items) {
  let total = 0;
  for (let i = 0; i <= items.length; i++) {
    total += items[i].price * items[i].qty;
  }
  return total;
}

export function addDelivery(subtotal, delivery) {
  return subtotal + delivery;
}

export function applyPromo(total, code) {
  if (code === "sale") return Math.round(total * 0.9);
  return total;
}

export function checkout(cart) {
  const subtotal = calcSubtotal(cart.items);
  const withDelivery = addDelivery(subtotal, cart.delivery);
  return applyPromo(withDelivery, cart.promo);
}

import { checkout } from "./cart.mjs";

const cart = {
  items: [
    { name: "latte", price: 1500, qty: 2 },
    { name: "croissant", price: 1200, qty: 1 },
  ],
  delivery: "500",
  promo: "SALE",
};

console.log("Total:", checkout(cart));

Run node main.mjs and it crashes. The output is real, from Node.js 24; the long folder path is replaced with …:

$ node main.mjs
file:///…/cart.mjs:4
    total += items[i].price * items[i].qty;
                      ^

TypeError: Cannot read properties of undefined (reading 'price')
    at calcSubtotal (file:///…/cart.mjs:4:23)
    at checkout (file:///…/cart.mjs:19:20)
    at file:///…/main.mjs:12:23
    at ModuleJob.run (node:internal/modules/esm/module_job:439:25)
    at async node:internal/modules/esm/loader:643:26
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)

Node.js v24.18.0

According to the Node.js docs, the first line of a stack has the form “error class: message”, followed by frames, each starting with at. The most recent call is on top, the entry point at the bottom. The reading rule: find the first at line with your file, not node:internal or node_modules. That is where it broke, although the cause may sit further down the stack — in whoever passed the bad data.

Hypothesis: on some iteration items[i] is undefined. The array has two elements with indexes 0 and 1, but i <= items.length lets the loop reach index 2. This is the classic off-by-one error. The fix is a strict <.

With the loop fixed, the program prints Total: 4200500. No exception, but the result is absurd. No stack trace will appear — you have to narrow it down yourself. The fastest tool is temporary output right before the suspicious spot. console.table shows an array of objects as a table, and typeof shows a value's type:

console.table(cart.items);
console.log("delivery:", cart.delivery, typeof cart.delivery);

$ node main.mjs
┌─────────┬─────────────┬───────┬─────┐
│ (index) │ name        │ price │ qty │
├─────────┼─────────────┼───────┼─────┤
│ 0       │ 'latte'     │ 1500  │ 2   │
│ 1       │ 'croissant' │ 1200  │ 1   │
└─────────┴─────────────┴───────┴─────┘
delivery: 500 string
Total: 4200500

Hypothesis confirmed: delivery is the string "500", and + concatenates 4200 and "500" into "4200500". Data like this often comes from forms, query parameters and JSON where a number is quoted. Fix it at the boundary — convert to a number where the value enters the calculation:

--- a/cart.mjs
+++ b/cart.mjs
@@ -1,11 +1,11 @@
 export function calcSubtotal(items) {
   let total = 0;
-  for (let i = 0; i <= items.length; i++) {
+  for (let i = 0; i < items.length; i++) {
     total += items[i].price * items[i].qty;
   }
   return total;
 }

 export function addDelivery(subtotal, delivery) {
-  return subtotal + delivery;
+  return subtotal + Number(delivery);
 }

$ node main.mjs
Total: 4700

The total is 4700 — no discount. Nothing throws, all types are numbers. We need to pause inside applyPromo and see what happens. A breakpoint pauses execution before a line runs. The simplest way is the debugger; statement: it acts as a breakpoint when a debugger is attached and does nothing otherwise.

Add debugger; as the first line of applyPromo and run Node.js's built-in console debugger, node inspect. Below is a real session: cont continues to the next pause, bt prints the call stack, exec evaluates an expression, watch tracks a value, next steps to the next line.

$ node inspect main.mjs
< Debugger listening on ws://127.0.0.1:9229/31bee525-ecb9-4a6c-b9ea-f75545b276bf
< For help, see: https://nodejs.org/learn/getting-started/debugging
< 
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
< 
debug> Break on start in cart.mjs:1
> 1 export function calcSubtotal(items) {
  2   let total = 0;
  3   for (let i = 0; i < items.length; i++) {
debug> cont
debug> break in cart.mjs:14
 12 
 13 export function applyPromo(total, code) {
>14   debugger;
 15   if (code === "sale") return Math.round(total * 0.9);
 16   return total;
debug> bt
#0 applyPromo cart.mjs:14:2
#1 checkout cart.mjs:22:9
#2 (anonymous) main.mjs:12:22
#3 run node:internal/modules/esm/module_job:439:24
debug> exec code
'SALE'
debug> exec code === "sale"
false
debug> watch('total')
debug> next
debug> step in cart.mjs:15
Watchers:
  0: total = 4700

 13 export function applyPromo(total, code) {
 14   debugger;
>15   if (code === "sale") return Math.round(total * 0.9);
 16   return total;
 17 }
debug> cont
debug> < Total: 4700
< 
debug> < Waiting for the debugger to disconnect...
< 
debug> .exit

Facts from the debugger: code is 'SALE', and comparing it with "sale" gives false — the case differs. bt shows the same chain as the stack trace: applyPromo ← checkout ← main.mjs. Fix the comparison and remove debugger;:

-  if (code === "sale") return Math.round(total * 0.9);
+  if (code?.trim().toLowerCase() === "sale") return Math.round(total * 0.9);

$ node main.mjs
Total: 4230

The console debugger is useful for understanding the mechanics, but day to day a graphical one is more convenient. Underneath it is the same thing: Node.js started with --inspect opens a port for a debugger, and Chrome DevTools or VS Code connects to it. The default is 127.0.0.1:9229. --inspect-brk also pauses before the first line of your code so you have time to set breakpoints:

$ node --inspect-brk main.mjs
Debugger listening on ws://127.0.0.1:9229/5f699728-1ccb-4e05-ba8a-2afa59a35332
For help, see: https://nodejs.org/learn/getting-started/debugging

• Pause on exceptions: DevTools can pause on caught and uncaught exceptions — the debugger stops where the error is thrown, with all variables available.
• Restart frame in DevTools re-runs the current function without restarting the program — handy for stepping through it again after editing a value in Scope.
• A conditional breakpoint like i === items.length in the bug 1 loop pauses exactly on the faulty iteration instead of every one.

If a web app bug involves data from a server, start with the Network panel in DevTools: the status code and the request and response bodies often show right away whose side the problem is on. Requests, statuses and JSON are covered in detail in the “HTTP and JSON” lesson.