Reading stack traces to the failing line

Understanding Reading stack traces to the failing line

A stack trace is a list of the calls that had not returned yet at the moment the Error object was constructed. V8 prints a header line of the form `Name: message`, then one `at function (file:line:column)` line per frame, innermost call first, because the innermost call is the top of the stack being dumped. The capture happens inside `new Error(...)`, not at the `throw`, so an error object built in one place and thrown later still points at where it was built.

The topmost frame is where execution was, but not always where you can act: `at JSON.parse (<anonymous>)` or `at Array.map (<anonymous>)` means a built-in was running, and a path inside node_modules means a library was. Errors usually surface a call or two below the actual mistake, at the moment a bad value is finally dereferenced, so the useful starting point is the topmost frame whose path is a file you wrote. The column matters as much as the line: on `order.customer.address.city` it tells you which of the three property reads is the one that hit undefined.

Frames can be missing, and knowing why saves time. A callback run by a timer or an event listener starts on a fresh stack, so the function that called setTimeout or addEventListener is simply not in the trace; errors crossing an `await` do keep their caller frames, because V8 stitches the resumed stack back together. V8 also records only the innermost `Error.stackTraceLimit` frames, ten by default, which is why deep recursion arrives truncated. Line and column numbers describe the file the engine actually loaded, so bundled or transpiled code needs source maps before those numbers mean anything in your source.

Treat the trace as an answer to "how did control reach this line", not "who produced this bad value"; the second answer is found by walking down the frames and logging what each caller passed in.

function toCents(price) {
  if (typeof price !== 'string') {
    throw new TypeError('price must be a string, got ' + typeof price);
  }
  return Math.round(Number(price) * 100);
}

function lineTotal(item) {
  return toCents(item.price) * item.qty;
}

function cartTotal(items) {
  let cents = 0;
  for (const item of items) {
    cents += lineTotal(item);
  }
  return cents;
}

try {
  cartTotal([{ price: '1.50', qty: 2 }, { price: 3, qty: 1 }]);
} catch (err) {
  console.log(err.stack.split('\n')[0]);
  err.stack.split('\n').slice(1, 4).forEach((frame, i) => {
    console.log(i === 0 ? 'threw in:' : 'called from:', frame.trim().split(' ')[1]);
  });
}

Worked examples

function scheduleWork() {
  setTimeout(runJob, 0);
}

function runJob() {
  try {
    JSON.parse('{oops}');
  } catch (err) {
    const frames = err.stack.split('\n').slice(1);
    console.log('frame 1:', frames[0].trim().split(' ')[1]);
    console.log('frame 2:', frames[1].trim().split(' ')[1]);
    console.log('scheduleWork in stack?', err.stack.includes('scheduleWork'));
  }
}

scheduleWork();

Error.stackTraceLimit = 3;

function countdown(n) {
  if (n === 0) throw new Error('hit zero');
  return countdown(n - 1);
}

try {
  countdown(50);
} catch (err) {
  const frames = err.stack.split('\n').slice(1);
  console.log('frames kept:', frames.length);
  console.log(frames.map((f) => f.trim().split(' ')[1]).join(' <- '));
}

class Cart {
  add(item) {
    return item.price.toFixed(2);
  }
}

const money = {
  format(n) {
    return n.toFixed(2);
  }
};

function plain(n) {
  return n.toFixed(2);
}

function topFrame(fn) {
  try {
    fn();
  } catch (err) {
    return err.stack.split('\n')[1].trim().split(' ')[1];
  }
}

console.log(topFrame(() => new Cart().add({})));
console.log(topFrame(() => money.format(undefined)));
console.log(topFrame(() => plain(null)));

Important notes

Common mistakes

Try it yourself