Stack traces & the stack trace API

A stack trace is a list of calls

A stack trace is a list of the function calls that were still running at one moment in your program. Each line in the list is one call. Tools call one line a frame. The newest call is at the top.

Say an error shows at renderInvoice above at checkout. That means checkout called renderInvoice, and the error happened inside renderInvoice.

This lesson is not about reading an everyday error. For that, see Reading errors, Custom errors, try/catch, and the debugging lessons. Here you will see how the list is made, and where tools can change it.

A stack trace goes through four steps:

1. Your code makes an error object.
2. The engine writes down the calls that are running. Each engine has its own limit on how many it keeps.
3. Later, some code reads error.stack. Only then does the engine turn the list into text.
4. A tool may change the file names and line numbers in that text to point at the files you wrote.

All the code in this lesson runs straight through, one line after another. Code that waits, with await or promises, comes in the next lesson, Async stack traces.

The list is written down when the error is made

In V8, new Error() writes down the list of calls at the moment the error object is made. It does not wait until the error is thrown. This surprises people who make an error early, keep it, and throw it later from somewhere else.

In the code below, top-level code means code that is not inside any function. Step through it and watch line 2 and line 8.

1function makeError() {2  const error = new Error("plate fell");3  return error;4}5 6function throwLater(error) {7  try {8    throw error;9  } catch (caught) {10    return caught.stack.split("\n").slice(0, 4);11  }12}13 14const capturedError = makeError();Run15const firstLines = throwLater(capturedError);16console.log(firstLines[1].includes("makeError"));17console.log(firstLines.some((line) => line.includes("throwLater")));

Line 2 makes the error inside makeError. Line 8 throws the same object later, inside throwLater.

• The first console.log prints true. The stack names makeError, because the list was written down there.
• The second prints false. throwLater was not running when the list was written down, so it is not in it.

This gives a useful habit: make the error at the place where things go wrong. If you make it much earlier, your logs will point at the function that made the error. They will not point at the place where your code decided to fail.

Hide a helper, and choose how many calls to keep

Error.captureStackTrace(target, hiddenFunction) writes a stack onto any object you give it, as a stack property. It takes two arguments:

• target: the object that gets the stack property.
• hiddenFunction (optional): a function to leave out. The list then starts just below this function. The function itself and every call above it are left out.

Error helpers use this to hide their own code, so the stack starts at the code that called them.

1function publicApi() {2  const marker = { name: "StackMarker" };3  Error.captureStackTrace(marker, publicApi);4  return marker.stack.split("\n").slice(0, 4).map((line) => line.trim());5}6 7function userCode() {8  return publicApi();9}10 11const lines = userCode();12console.log(typeof Error.captureStackTrace);13console.log(lines[0]);14console.log(lines[1].includes("userCode"));15console.log(lines.some((line) => line.includes("publicApi")));

Line by line:

• Line 2 makes a plain object, marker. Its name becomes the first line of its stack.
• Line 3 writes a stack onto marker and leaves out publicApi.
• Line 4 cuts the stack text into lines with split("\n"), keeps the first four with slice(0, 4), and removes spaces at each end with trim().
• Line 12 prints function, so this engine has captureStackTrace.
• Line 13 prints StackMarker, the first line.
• Line 14 prints true: the first call in the list is userCode.
• Line 15 prints false. some() asks "does any line name publicApi?" None does.

captureStackTrace started in V8. MDN's browser support tables now list it in new Firefox and Safari too. Old browsers and small engines may not have it, so check that it exists before you call it.

In the playground, deep(6) calls itself again and again until its number reaches 0: seven deep calls in a row. The last one makes the error. Pick a limit, press Run, and count the calls that are kept.

1const previousLimit = Error.stackTraceLimit;2Error.stackTraceLimit = 3;3 4function deep(level) {5  if (level === 0) return new Error("limit check").stack;6  return deep(level - 1);7}8 9const lines = deep(6).split("\n");10console.log(lines.slice(1).length);11Error.stackTraceLimit = previousLimit;

Error.stackTraceLimit is a number that V8 reads each time an error is made. It is 10 unless you change it.

• 0 keeps no calls at all.
• A whole number, like 3, keeps at most that many calls.
• Infinity keeps every call.

The setting belongs to one page, or one iframe, in Chrome. V8 calls this a context. Changing it on one page does not change it on another.

Each row of this table is one stack tool. Read across to see what it does and what to be careful about.

Make your own stack text with prepareStackTrace

Error.prepareStackTrace is a V8 setting that holds a function. V8 calls that function when it turns a list of calls into stack text. It passes in two things:

• the error object;
• an array of CallSite objects, newest call first. A CallSite describes one call in the list.

A CallSite has methods that answer questions about its call: the function name, the file name, the line, the column, whether the function was called with new, and more. Whatever your function returns becomes the value of error.stack.

1const previous = Error.prepareStackTrace;Run2 3Error.prepareStackTrace = (error, callSites) => {4  const first = callSites[0];5  return {6    message: error.message,7    functionName: first.getFunctionName(),8    line: first.getLineNumber(),9    native: first.isNative(),10  };11};12 13function inspectStack() {14  const error = new Error("custom format");15  return error.stack;16}17 18const stack = inspectStack();19console.log(stack.functionName);20console.log(typeof stack.line);21console.log(stack.native);22 23Error.prepareStackTrace = previous;

This example returns an object instead of text. That shows V8 accepts any value your function returns.

• Line 1 saves the old function in previous.
• Line 3 puts in the new function.
• Line 7 asks the newest CallSite for its function name. It is inspectStack, the function that made the error.
• Line 8 asks for its line number.
• Line 23 puts the old function back. Real tools must do this. The setting changes every stack on the page, not just this one.

If you change this setting:

• keep your function very small;
• put the old function back inside finally, the block that runs whether or not an error is thrown;
• don't change it in a website unless you control all the code on the page.

Logging tools and test runners are better places for it.

Source maps point the stack at the file you wrote

The JavaScript that runs on a real website is often not the code you wrote. A build tool changes it first. It may:

• join many files into one (this is called bundling);
• shorten names and remove spaces to make the file smaller (minifying);
• turn TypeScript into JavaScript.

Then the stack trace names the built file, not yours. A source map is a file that links each place in the built file back to a place in the file you wrote. Browser DevTools use source maps for stack traces. Node.js does too, when you start it with --enable-source-maps.

1// compiled-stack-demo.js, produced by a build tool2function crash() {3  throw new Error("mapped");4}5crash();6//# sourceMappingURL=data:application/json;base64,...

Line 3 throws the error. Line 6 is a comment that tells tools where the source map is. Here the map is written right into the comment (the ... stands for the long map text).

The built file is still the code that runs. The map only changes the file names and line numbers that the stack trace shows. It is a feature of the tools, not a rule of the JavaScript language.

Be careful when you put source maps on a public website. They are great for finding bugs. But anyone can download them, and a full map can show your original code, names, and comments. Your team should decide how much it is happy to share.

Which stack tools work everywhere?

TC39 is the group that writes the official rules of JavaScript. A new idea goes through stages, from Stage 0 to Stage 4. Stage 4 means it is finished and part of the language. Stage 3 means it is nearly finished.

Today, error.stack is not fully in the official rules. Every major engine has it, but each one behaves a little differently. There are two TC39 proposals about it:

• The Error stack accessor proposal is at Stage 3. It writes down the shape that Error.prototype.stack has had for years.
• The older, bigger Error Stacks proposal is still at Stage 1.

An accessor is a property that runs a function when you read it (a getter) or write it (a setter). Object.getOwnPropertyDescriptor returns a small object that describes one property. For an accessor, its get and set fields hold those two functions.

1const descriptor = Object.getOwnPropertyDescriptor(new Error("proposal"), "stack");2console.log(typeof descriptor.get);3console.log(typeof descriptor.set);4console.log(descriptor.enumerable);5console.log(descriptor.configurable);

In Node.js 22 (with V8 12.4), this prints:

• Line 2: function. There is a getter.
• Line 3: function. There is a setter.
• Line 4: false. stack does not show up when you loop over the error's properties.
• Line 5: true. The property can be changed or deleted.

Other engines are different. Safari has used a different shape in the past. Firefox has kept the getter on Error.prototype, not on each error. That is why TC39 is writing down only the shared part. It is not trying to make every engine's stack text the same.

Each row of this table is one stack tool. Read across to see where it works today and how to use it.

Use stack tools safely

Developers mostly need stack traces for three jobs:

• logs, which record what went wrong on a live site;
• test results, which show where a failing test broke;
• developer tools, such as debuggers and error reporters.

In everyday website code, use simple custom error classes and clear messages. Use the V8 settings only when you control everything that runs, or when you are writing a tool for Node.js or Chrome.

• Make a new error at the place where things go wrong, so its stack points there.
• Use captureStackTrace to hide helper functions. Check that it exists first, for older engines.
• Raise stackTraceLimit only while you look for a bug. Then put the old value back.
• Put the old prepareStackTrace back inside finally. It changes every stack on the page.
• Turn on source maps for your live site only if your team is happy for people to see the original code.

The lessons Debugging in the browser and Advanced debugging show how to use DevTools. This lesson explains what is behind the stack traces those tools show.

Common misconceptions

• "The stack is written down when I throw." In V8, an error's stack is written down when the error is made.
• "error.stack is in the official rules, like message." Every major engine has it, but the exact behavior and the text are still being written into the rules.
• "Source maps change what runs." They only change the file names and line numbers that a stack trace shows.
• "prepareStackTrace is safe to change in any website." It is a V8 setting that changes every stack on the page. Use it only in tools you control, and put the old one back.
• "A longer stack is always better." Longer stacks use more memory. They can also show private details about how your code works.

Each row of this table is one pair of ideas that people mix up. Read across: the right idea, then what it is not.

Practice exercises

function makeError() {
  return new Error("packed");
}
function deliver(error) {
  try {
    throw error;
  } catch (caught) {
    return caught.stack;
  }
}
const error = makeError();
const stack = deliver(error);
console.log(stack.includes("makeError"));
console.log(stack.includes("deliver"));

function publicApi() {
  const marker = { name: "StackMarker" };
  Error.captureStackTrace(marker, publicApi);
  return marker.stack.split("\n")[1];
}
function userCode() {
  return publicApi();
}
console.log(userCode().includes("userCode"));

const oldLimit = Error.stackTraceLimit;
Error.stackTraceLimit = 2;
function a() {
  return b();
}
function b() {
  return new Error("short").stack.split("\n").slice(1).length;
}
console.log(a());
Error.stackTraceLimit = oldLimit;

const previous = Error.prepareStackTrace;
try {
  Error.prepareStackTrace = () => "short";
  console.log(new Error("x").stack);
} finally {
  Error.prepareStackTrace = previous;
}

Quiz

These questions check five moments: making an error, throwing it, turning the stack into text, mapping it to your files, and what is in the official rules. The lesson tests run each code question in Node.js to check the answer.

Key takeaways

• In V8, an error writes down its list of calls when it is made. It turns the list into text only when stack is first read.
• Error.captureStackTrace writes a stack onto any object and can leave helper functions out. Error.stackTraceLimit sets how many calls V8 keeps.
• Error.prepareStackTrace gets a list of V8 CallSite objects. It changes every stack on the page, and only V8 has it.
• Source maps change the file names and line numbers a stack shows. They don't change what runs.
• The Error stack accessor proposal is at Stage 3. It covers the stack property, not V8's own settings like prepareStackTrace.

Next, Async stack traces shows how engines rebuild the list of calls when code waits, with await, promises, and callbacks.