Async stack traces

What an async stack trace is

A stack trace is the list of function calls that led to the current line. JavaScript keeps this list on the call stack. Each function call adds one entry, called a frame. Each return removes that frame.

A normal stack trace answers one question: "Which functions called this one, right now?"

Async code adds a second question. Async code is code that runs later, such as a timer callback or the code after an await. The second question is: "Which code asked for this work to run later?" Asking for work to run later is called scheduling it.

• The answer to the first question is the live call stack: the functions running right now.
• The answer to the second question is the async ancestry: the chain of code that scheduled the work.

This lesson is about finding bugs, which is called debugging. Other lessons explain how the waiting itself works: the event loop, microtasks, promises, and async and await.

Stack traces and the stack trace API covers Error.stack and how to change its format. The next lesson, Suspending frames: generators & async functions, shows how an await saves a paused function.

Why the caller goes missing

A normal call stack only lasts while code runs. One piece of work that runs from start to finish is called a job. When a job finishes, the stack is empty again. Control goes back to the host: the program that runs JavaScript, such as the browser or Node.

Later, the host starts the next job with a fresh, empty stack. That job can be a timer callback or the code after an await. The function that scheduled it is not on the stack any more.

1function startTimer() {2  setTimeout(() => {3    const stack = new Error("inside timer").stack ?? "";4    console.log(stack.includes("startTimer"));5  }, 0);6}7 8startTimer();

Line 8 calls startTimer. Line 2 asks for a timer, and then startTimer returns. Later, the timer callback runs. Line 3 makes a new error inside it and reads the error's stack text. That text lists the frames on the stack right then.

In Node 22, line 4 prints false: the text does not contain startTimer. Line 8 called it, but that call ended before the timer ran.

1const stack = ["script"];Run2const queue = [];3function outer() {4  stack.push("outer");5  schedule("resume outer");6  stack.pop();7}8function schedule(label) {9  queue.push({ label, asyncParent: "outer" });10}11outer();12const job = queue.shift();13stack.length = 0;14stack.push("microtask");15console.log(job.label);16console.log(job.asyncParent);

Step through this small model. It is a teaching model: a plain array called stack stands for the call stack. Real engines do not use this array, but the idea is the same.

• Line 6 removes outer from stack, just like a return does.
• Line 9 saves a note in the job: its parent is outer.
• Line 13 empties stack before the later job starts.
• Line 16 still prints outer, because the job kept that note.

So the live stack and the async ancestry are two separate things. The first is gone; the second can be saved.

Zero-cost async stack traces in V8

V8 is the JavaScript engine inside Chrome and Node. V8's stack trace documentation says the --async-stack-traces setting has been on by default since V8 7.3. A setting like this, given when the engine starts, is called a flag.

V8 calls this feature zero-cost. It does not save a copy of the stack each time work is scheduled. Instead, when an error happens, it rebuilds the missing callers. It does this by following the links between promises. A promise is an object for a result that arrives later.

V8's documentation lists the cases it covers:

• lines with await
• Promise.all()
• Promise.any()

First, step through a small model of how V8 follows the awaits back to the callers.

1const promiseChain = [];Run2function rememberAwait(caller, awaited) {3  promiseChain.push(caller + " awaits " + awaited);4}5function c() {6  promiseChain.push("c throws after await");7  return "Error: boom";8}9function b() {10  rememberAwait("b", "c");11  return c();12}13function a() {14  rememberAwait("a", "b");15  return b();16}17const error = a();18const asyncFrames = promiseChain19  .filter((step) => step.includes("awaits"))20  .reverse();21console.log(error);22console.log(asyncFrames.join(" -> "));

Now the real thing. The code below only runs in Node, because it reads process.version. That is why it has no Run button.

1async function c() {2  await 0;3  throw new Error("boom");4}5async function b() {6  await c();7}8async function a() {9  await b();10}11 12a().catch((error) => {13  const stack = String(error.stack);14  console.log(/^v22\./.test(process.version));15  console.log(/^12\.4\./.test(process.versions.v8));16  console.log(stack.includes("at async b"));17  console.log(stack.includes("at async a"));18});

Promise.all() takes a list of promises and waits for all of them. When one of them fails, V8 adds a special line for it.

1async function c() {2  await 0;3  throw new Error("boom");4}5async function b() {6  await Promise.all([c()]);7}8async function a() {9  await b();10}11 12a().catch((error) => {13  const stack = String(error.stack);14  console.log(stack.includes("at async Promise.all"));15  console.log(stack.includes("at async b"));16  console.log(stack.includes("at async a"));17});

All three checks print true. Line 14 looks for the special line. In Node 22 it reads at async Promise.all (index 0): the first promise in the list failed. After it come at async b and at async a.

Keep in mind: this is a V8 feature, not a rule of the JavaScript language. Stack text looks different in other engines and versions. The program does the same thing either way. Only the text you read while debugging changes.

Async call stacks in DevTools

DevTools are the developer tools built into the browser. Chrome DevTools has its own way to show async callers. Its async call stack guide shows the Async checkbox. It sits in the Call Stack pane of the Sources panel.

When this checkbox is on, DevTools writes down where each piece of async work was scheduled. Later, when your code pauses inside a callback, DevTools can show where that callback came from. This works for timers, network requests (fetch and XHR), promises, animation frames, mutation observers, and more. V8's zero-cost error.stack does not cover most of these.

The table below compares three ways to see async callers. Each row is one way: where you see it, what it shows, and what it costs.

Your own code can help DevTools too. A scheduler is code that decides when other work runs; frameworks often have one. The code below links later work to the place it started, using console.createTask.

1const task = console.createTask("checkout submit");2 3button.addEventListener("click", () => {4  setTimeout(() => {5    task.run(() => {6      saveOrder();7    });8  }, 0);9});

The Chrome Console API describes console.createTask(name).

• Line 1 makes a task object. It remembers the stack at that moment.
• Line 5 runs the later work through task.run(fn).
• DevTools then links the later work on line 6 back to line 1.

button and saveOrder stand for your own page's button and function.

Long stack traces in Node.js

Node runs JavaScript with V8. So Node gets V8's zero-cost async stack traces for the same promise cases.

Node also has Error.stackTraceLimit. It sets how many frames V8 collects for each new error. The default is 10. Raise it when a long chain of calls gets cut off before the frame you need.

1Error.stackTraceLimit = 2;2function one() { two(); }3function two() { three(); }4function three() { throw new Error("short"); }5 6try {7  one();8} catch (error) {9  const frameCount = String(error.stack)10    .split("\n")11    .filter((line) => line.trim().startsWith("at ")).length;12  console.log(frameCount <= 2);13}

Line 1 sets the limit to 2. Lines 9 to 11 count the stack lines that start with at. Line 12 prints true: no more than two frames were kept.

Before V8 had async frames, Node projects used long stack trace tools. These came from libraries, not from Node itself. The idea is simple:

• When work is scheduled, save the stack right away.
• When that work later throws an error, add the saved stack to the error.

Node also has a low-level API, async_hooks, that can track async work. Node's own docs strongly advise against using async_hooks unless you really need it.

1function scheduleWithCapturedStack(work) {2  const scheduledStack = new Error("Scheduled here").stack ?? "";3  setTimeout(() => {4    try {5      work();6    } catch (error) {7      const combined = String(error.stack).split("\n")[0]8        + "\n--- async boundary ---\n"9        + scheduledStack.split("\n")[1].trim();10      console.log(combined.includes("async boundary"));11    }12  }, 0);13}14 15scheduleWithCapturedStack(() => {16  throw new Error("lost parcel");17});

• Line 2 saves the stack while the work is being scheduled.
• Line 16 throws an error inside the later callback.
• Lines 7 to 9 join three things: the first line of the new error, a --- async boundary --- line, and one line from the saved stack.
• Line 10 prints true: the joined text has the boundary line in it.

await vs then: which is easier to debug

await and .then() both wait for promises. They leave different clues in the stack.

• With await: in V8 12.4, an async function that awaits another one shows up as at async plus its name when the other one fails.
• With .then(): a chain of .then() callbacks often loses the names of the outer functions in error.stack.

1function c() {2  return Promise.resolve().then(() => {3    throw new Error("boom");4  });5}6function b() {7  return c().then((value) => value);8}9function a() {10  return b().then((value) => value);11}12 13a().catch((error) => {14  const stack = String(error.stack);15  console.log(stack.includes("at b "));16  console.log(stack.includes("at a "));17});

Line 3 throws inside a .then() callback. Lines 15 and 16 both print false: b and a are not in the stack.

Timers are different again. A timer callback is not part of an await chain, even when an async function waits for it.

1function waitForTimer() {2  return new Promise((_, reject) => {3    setTimeout(() => reject(new Error("boom")), 0);4  });5}6async function timerOuter() {7  await waitForTimer();8}9 10timerOuter().catch((error) => {11  const stack = String(error.stack);12  console.log(stack.includes("timerOuter"));13  console.log(/Timeout|setTimeout/.test(stack));14});

• Line 3 makes the error inside a timer callback.
• Line 7: timerOuter awaits that promise.
• Line 12 prints false: timerOuter is not in the stack.
• Line 13 prints true: the stack shows Node's timer code instead, such as Timeout._onTimeout.

Try it in your own browser. Pick a case and run it to see your browser's real stack text.

1async function awaitVersion() {2  async function c() {3    await 0;4    throw new Error("boom");5  }6  async function b() { await c(); }7  async function a() { await b(); }8  await a();9}10 11function thenVersion() {12  function c() {13    return Promise.resolve().then(() => { throw new Error("boom"); });14  }15  function b() { return c().then((value) => value); }16  function a() { return b().then((value) => value); }17  return a();18}

Run the case to see your browser's real stack text.

The table below sums it up. Each row is one way to write the code, the clue it leaves in V8 12.4, and what to do about it.

Practical debugging habits

Use async and await when they make the code read from top to bottom. They also keep function names in the stack. Keep .then() where it makes the code clearer. Just know that the stack may show fewer names.

1async function fetchReceipt() {2  await 0;3  throw new Error("payment failed");4}5 6async function checkout() {7  try {8    return await fetchReceipt();9  } catch (error) {10    console.log("checkout saw " + error.message);11  }12}13 14checkout();

Line 8 uses return await on purpose. The await waits for the promise inside the try block. When the promise fails, the error is thrown right there, on line 8. The catch on line 9 handles it, and line 10 prints checkout saw payment failed.

Without await, the failed promise would leave the try block first, and this catch would never see it. The promise errors lesson explains this rule in more depth.

These habits make async bugs easier to find:

• Give async functions clear names. loadCart and saveReceipt tell you more in a stack than run.
• Raise Error.stackTraceLimit only while debugging. More frames cost time on every error, so don't raise it in code that runs on every request.
• When you wrap one error in a new one, pass the first as cause: new Error("Checkout failed", { cause: error }). The new error then points back to the first one.
• For bugs in callbacks, turn on DevTools async stacks. Measure your app's speed before you add a long stack trace library.

Common misconceptions

• "The old stack is still there somewhere." It is not. The old stack is gone. Async frames are rebuilt or recorded to help you debug.
• "Zero-cost means every async callback is covered." V8 lists only await, Promise.all(), and Promise.any(). Timers and other callbacks are not covered.
• "Stack text looks the same everywhere." The JavaScript standard does not define the text of Error.stack. Each engine and tool picks its own format.
• "Long stack traces are free." Saving a stack each time work is scheduled costs time and memory, especially in busy Node servers.
• "Always rewrite every .then chain with await." Pick what is clearest. Use await where it makes the code easier to read and the stack easier to follow.

Some ideas in this lesson sound alike. Each row below names one idea, says what it means, and how it is different from the others.

Practice exercises

async function demo() {
  console.log("one");
  await 0;
  console.log("three");
}
demo();
console.log("two");

function startTimer() {
  setTimeout(() => {
    const stack = new Error("inside timer").stack ?? "";
    console.log(stack.includes("startTimer"));
  }, 0);
}
startTimer();

async function readReceipt() {
  await 0;
  throw new Error("offline");
}
async function checkout() {
  try {
    return await readReceipt();
  } catch (error) {
    console.log("handled " + error.message);
  }
}
checkout();

async function readReceipt() {
  await 0;
  throw new Error("offline");
}
async function checkout() {
  try {
    return await readReceipt();
  } catch (error) {
    console.log("handled " + error.message);
  }
}
checkout();

Check your understanding

Key takeaways

• The live call stack is empty again when a job finishes. Async ancestry, the code that scheduled the work, is a separate thing.
• V8's zero-cost async stack traces are on by default. They rebuild the callers for await, Promise.all(), and Promise.any().
• Timers, event listeners, and many .then() callbacks need DevTools or your own saved stack to show where they were scheduled.
• Node gets V8's async frames, has Error.stackTraceLimit, and can use long stack trace libraries, with care.
• Use await where it keeps code readable and gives better stack clues. Don't write code just to change the stack text.

One-line summary: an async stack trace is not the old stack kept forever. It is the best story the engine or a tool can rebuild or record about why later work is running.

Next, Suspending frames: generators & async functions explains how JavaScript saves a paused function so it can carry on later.