Async stack traces

Async stack traces in one picture

A normal stack trace answers “who called this function right now?” Async JavaScript adds a harder question: “who scheduled the work that is running now?” The first question is the live call stack. The second is async ancestry.

This lesson stays focused on diagnostics. The event loop, microtasks, promises, and async and await explain the scheduling rules. Stack traces and the stack trace API covers Error.stack, Error.captureStackTrace, and custom formatting. The next lesson, Suspending frames: generators & async functions, goes deeper on how an await saves a function's state.

Why async stacks break

A synchronous stack is short-lived. When line 8 schedules a timer or line 6 reaches an await, the current job eventually returns to the host. Later, the event loop or microtask queue starts a new job from a fresh entry point. The old caller is not on the machine stack anymore.

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

In Node 22, this prints false: the stack captured inside the timer does not include startTimer. Line 2 is the later callback. Line 8 scheduled it, but that scheduling call already finished.

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 the teaching model. Line 6 returns from outer, so the live stack loses that frame. Line 16 can still print a saved async parent because the job carried a breadcrumb. Real engines do not use this array, but the distinction is accurate: live stack and async ancestry are different facts.

Zero-cost async stack traces

V8's stack trace API documentation says --async-stack-traces is on by default since V8 7.3. The feature is called zero-cost because V8 can reconstruct supported async frames from promise relationships instead of recording every scheduling stack. The supported cases documented there are await locations, Promise.all(), and Promise.any().

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

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

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

Notice the scope: this is an implementation feature in V8, not a JavaScript semantic guarantee. Stack strings vary across engines and versions. The program's behavior is still the same promise rejection; the debugging story is what changes.

Async call stacks in DevTools

Chrome DevTools has a different tool-level feature. Its async call stack guide shows the Sources panel's Async checkbox in the Call Stack pane. When DevTools records async operations, it can link a later callback back to the scheduling site for timers, XHR or fetch work, promises, animation frames, mutation observers, and more. That helps for cases V8's zero-cost error.stack will not cover.

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 documents console.createTask(name) as a way to associate the current stack with a task object, then run later work through task.run(fn). Frameworks and custom schedulers can use that link so DevTools shows better async stacks.

Long stack traces in Node.js

Node uses V8, so modern Node inherits V8's zero-cost async stack traces for supported promise relationships. Node also exposes Error.stackTraceLimit, which controls how many frames V8 collects in the current context. That is useful when a deep call chain is clipped before the interesting frame.

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}

Before V8's built-in async frames, Node projects often used userland “long stack trace” tools. The basic trick is to capture a stack at scheduling time and append it when the later error happens. Libraries can do this more completely, and Node's async_hooks API can track async resources, but Node's docs strongly discourage casual async_hooks use because it is a low-level API.

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

await vs then for debuggability

await and .then() both compose promises, but they leave different debugging evidence. In V8 12.4, an async wrapper that actually awaits a child can appear as at async wrapper after the child rejects. A chain that bounces through .then() callbacks often loses those outer helper names 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});

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

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 capture your browser's real stack string.

Practical debugging habits

Prefer async/await when it makes the control flow read from top to bottom and when wrapper functions matter in diagnostics. Keep .then() where it makes composition clearer, but know what you trade away in stack readability.

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 is intentionally return await. Without await, the rejected promise would leave the try block before the local catch could handle it. The promise errors lesson goes deeper on that rule.

• Keep wrapper names meaningful: loadCart and saveReceipt are better stack clues than run.
• Set Error.stackTraceLimit deliberately in diagnostics, not in every hot request path.
• Use error.cause when wrapping failures so a higher-level error points back to the original one.
• Open DevTools async stacks for callback-heavy bugs; use production measurements before adding long-stack libraries.

Common misconceptions

• “The stack never really disappeared.” It did. Async frames are reconstructed or recorded debugging context.
• “Zero-cost means every async callback is covered.” V8 documents await, Promise.all(), and Promise.any(), not arbitrary timers.
• “Stack strings are standardized.” JavaScript does not standardize Error.stack text; engines and tools choose formats.
• “Long stacks are free.” Capturing scheduling stacks can cost CPU and memory, especially in busy Node services.
• “Always rewrite every chain to await.” Prefer clarity. Use await where it improves readability and diagnostics.

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 synchronous stack ends when a job returns; async ancestry is separate debugging evidence.
• V8's zero-cost async stacks are on by default and reconstruct supported await, Promise.all(), and Promise.any() relationships.
• Timers, event listeners, and many .then() callbacks need DevTools recording or explicit context if you want their scheduling site.
• Node inherits V8's async frames, exposes Error.stackTraceLimit, and can use userland long stacks with care.
• Prefer await where it keeps code readable and improves stack clues; do not optimize for stack text alone.

One-line summary: async stack traces are not the old stack preserved forever; they are the best reconstructed or recorded story of why later work is running. Next, Suspending frames: generators & async functions explains how JavaScript saves a paused function's state so it can resume later.