Stack traces & the stack trace API

A stack trace is a captured route

A stack trace is a list of active calls that led to a point in your program. When an error says at renderInvoice above at checkout, it is showing the path through function calls, newest frame first.

This lesson is not the everyday “how do I read an error?” path. For that, use Reading errors, Custom errors, try/catch, and the debugging lessons. Here we look at how the stack is built and where tool authors can hook into it.

1. Create an error object near the interesting moment.
2. The engine records frames, with engine-specific limits.
3. Later code reads error.stack, so the engine formats those frames.
4. Tooling may remap generated locations back to original source files.

We will stay synchronous in this lesson. The next lesson, Async stack traces, explains how await and promises add missing asynchronous history.

Captured when the Error is made

In V8, new Error() captures the stack when the object is constructed, not when it is thrown. That detail surprises people who create one error early, keep it around, and throw it somewhere else later.

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 constructs the error. Line 8 throws the same object later. The first printed value is true because the captured stack includes makeError. The second printed value is false because throwLater was not part of the original capture.

This also explains a practical habit: create the error at the failure boundary. If you create it long before the failure, your logs will point at the factory, not the place where the decision to fail happened.

captureStackTrace and stackTraceLimit

Error.captureStackTrace(target, hiddenFunction) installs stack information on any object. The second argument asks V8 and supporting engines to omit frames above that function, including the function itself. Error helpers use this to hide plumbing.

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 3 captures a stack on marker and hides publicApi. Line 14 proves the first useful frame is userCode. Line 15 proves the helper frame is gone. MDN's browser-compat data now lists modern Firefox and Safari support, but old browsers and smaller engines still need a feature check.

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 defaults to 10 in V8. Setting it to 0 disables collection, a finite integer caps frames, and Infinity asks for all available frames. The setting is per V8 context, which usually means one page or iframe in Chrome.

prepareStackTrace and CallSite objects

V8's Error.prepareStackTrace is a global formatter hook. When V8 formats a stack, it calls your function with the error and an array of CallSite objects. A CallSite is a structured object for one frame: it can report the function name, file name, line, column, whether the call was a constructor, and more.

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;

The example returns an object instead of a string to prove that V8 accepts any formatter result. Line 7 reads the newest CallSite's function name. Line 8 stores its line number. Line 23 restores the previous formatter, which is not optional in real tools because the hook affects every stack formatted in that context.

If you customize this hook, keep the formatter tiny, wrap changes in try/finally, and avoid shipping a global formatter in a browser app unless you own the whole runtime. Logging frameworks and test runners are better homes for it.

Source-mapped stack traces

Production JavaScript often runs after bundling, minifying, or compiling TypeScript. A source map is a file that maps a generated location back to the original source location. DevTools uses maps for browser stacks, and Node can do the same 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,...

The generated file still executes. The map only changes reported locations. The lesson test runs a child Node process with an inline source map and --enable-source-maps, then asserts that the thrown stack names original-stack-demo.ts. That is a tooling fact, not a new JavaScript semantic rule.

In a real site, publish source maps only with the privacy level your team accepts. They are excellent for debugging, but they can reveal original names and comments if you upload full maps publicly.

Proposals and engine support

Today, error.stack is a de facto property, not fully standardized behavior. The TC39 Error stack accessor proposal is Stage 3 and focuses on standardizing the long-existing Error.prototype.stack accessor shape. The older broader Error Stacks proposal remains Stage 1.

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);

Node 22 with V8 12.4 prints function, function, false, and true for that descriptor. Safari's historical shape differs, and Firefox has used a prototype accessor. That is exactly why TC39 is standardizing the common surface carefully instead of standardizing every engine's stack internals.

Use stack power safely

Working developers usually need stacks for three jobs: logs, test diagnostics, and developer tools. In app code, prefer simple custom error classes and clear messages. Reach for V8 hooks only when you control the runtime or are writing tooling for Node and Chrome.

• Create fresh errors at the failure boundary so the construction stack is meaningful.
• Use captureStackTrace to hide helper frames, with a feature check for older engines.
• Raise stackTraceLimit only around diagnostics, then restore it.
• Restore prepareStackTrace in finally; it is global in the current context.
• Enable source maps in development and production observability only when the map exposure is acceptable.

Browser debugging lessons such as Debugging in the browser and Advanced debugging cover DevTools workflows. This lesson gives you the engine-level vocabulary for understanding what those tools display.

Common misconceptions

• “The stack is captured when I throw.” In V8, normal Error stacks are captured when the Error is constructed.
• “`error.stack` is standardized like `message`.” The property exists widely, but exact behavior and formatting are still being standardized.
• “Source maps change what ran.” They change reported source locations, not runtime execution.
• “`prepareStackTrace` is a safe app-level formatter.” It is a V8-specific global hook. Use it in controlled tooling and restore it.
• “A longer stack is always better.” Longer stacks cost memory and can expose private implementation details.

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

Check the difference between construction, throwing, formatting, mapping, and standardization. The code questions are proved by the lesson tests in Node/V8.

Key takeaways

• In V8, normal error stacks are captured at construction time and formatted lazily on first access.
• Error.captureStackTrace can install a stack and hide helper frames; Error.stackTraceLimit controls V8 frame count.
• Error.prepareStackTrace receives V8 CallSite objects, but it is global and engine-specific.
• Source maps remap displayed locations; they do not change runtime call order.
• The Error stack accessor proposal is Stage 3; it standardizes the stack property surface, not V8's formatter API.

Next, Async stack traces shows how engines reconstruct stack history across await, promise combinators, and callback boundaries.