The call stack

The stack of calls

JavaScript runs one piece of code at a time. That code might be at the top level of a script, which means it is not inside any function. It might be inside a function. Or it might be inside a function that another function called.

The call stack is the list JavaScript keeps of the function calls that are running right now. A stack is a pile where you add things on top and take them off the top.

Each entry in the call stack is called a stack frame, or just a frame. One frame stands for one call. In the last lesson, Execution contexts, you saw what a call needs to run: its parameters, its local variables, and links to outer scopes. The frame holds on to that context. It also remembers where to go back to when the call returns.

function greet(user) {
  console.log("Hello " + user);
}
greet("Asha");

Line 1 creates greet. It doesn't run yet. Line 4 calls it with "Asha". So JavaScript puts a frame for greet on top of the stack. Putting a frame on top is called a push.

greet prints Hello Asha and returns. Then its frame comes off the top. Taking a frame off is called a pop. After that, the script goes on.

The Recursion lesson used a pile of plates to show a function that calls itself. This lesson uses ordinary functions. You will:

• watch helper functions push and pop frames,
• read a stack trace from top to bottom,
• cause a stack overflow on purpose, safely,
• and use the Call Stack panel in DevTools.

Each time JavaScript calls a function, it pushes a frame. The function that made the call is called the caller. The caller stops and waits underneath. When the called function returns, its frame is popped. Then the caller goes on from the line where it stopped.

The checkout example below uses a few small helper functions:

• checkout calls calculateTotal, then applyCoupon, then formatReceipt.
• calculateTotal and applyCoupon both call roundPrice.

So roundPrice runs twice, for two different callers. Each of those calls gets its own frame. One function can have many frames: one for each call.

1function checkout(cart, coupon) {2  const subtotal = calculateTotal(cart);3  const discounted = applyCoupon(subtotal, coupon);4  const receipt = formatReceipt(discounted);5  return receipt;6}7function calculateTotal(cart) {8  const total = cart.items.reduce((sum, item) => sum + item.price, 0);9  return roundPrice(total);10}11function applyCoupon(total, coupon) {12  if (coupon === "SAVE10") {13    return roundPrice(total * 0.9);14  }15  return roundPrice(total);16}17function formatReceipt(total) {18  return "$" + total.toFixed(2);19}20function roundPrice(value) {21  return Math.round(value * 100) / 100;22}23checkout({ items: [{ price: 19.99 }, { price: 5 }] }, "SAVE10");Run

The step-through above shows the code line by line. The playground below shows the same run as a pile of cards. Each card is one frame, and the newest card is at the top. The cards are drawn from the steps of the checkout run. They don't show the engine's real memory.

1function checkout(cart, coupon) {2  const subtotal = calculateTotal(cart);3  const discounted = applyCoupon(subtotal, coupon);4  const receipt = formatReceipt(discounted);5  return receipt;6}7function calculateTotal(cart) {8  const total = cart.items.reduce((sum, item) => sum + item.price, 0);9  return roundPrice(total);10}11function applyCoupon(total, coupon) {12  if (coupon === "SAVE10") {13    return roundPrice(total * 0.9);14  }15  return roundPrice(total);16}17function formatReceipt(total) {18  return "$" + total.toFixed(2);19}20function roundPrice(value) {21  return Math.round(value * 100) / 100;22}23checkout({ items: [{ price: 19.99 }, { price: 5 }] }, "SAVE10");

A stack trace is a copy of the call stack, saved at the moment an error is made. It lists the frames that were on the stack at that moment.

An engine is the part of a browser or of Node.js that runs JavaScript. Chrome and Node.js use V8, Firefox uses SpiderMonkey, and Safari uses JavaScriptCore. Each engine writes a stack trace a little differently. But you read every trace the same way:

1. Start at the top. The first frame is where the error started.
2. Read down. Each frame below is the function that called the one above it.

1function checkout() {2  calculateTotal();3}4function calculateTotal() {5  applyCoupon();6}7function applyCoupon() {8  throw new Error("Coupon database is offline");9}10checkout();

Click Show stack trace to see the trace for this code.

The table below takes that stack trace apart, one line at a time. Read each row as: "this line of the trace means this, and here is how to use it."

1Error: Coupon database is offline2    at applyCoupon (checkout.js:8:9)3    at calculateTotal (checkout.js:5:3)4    at checkout (checkout.js:2:3)5    at checkout.js:10:1

function saveProfile() {
  validateProfile();
}
function validateProfile() {
  console.trace("profile validation");
}
saveProfile();

console.trace() prints a stack trace at the line where you call it. Nothing has to throw. In this example, line 5 calls it inside validateProfile. So the trace shows validateProfile on top and saveProfile under it. Each browser and Node print it in their own format, so your output may look a little different.

A function with no name is called an anonymous function. Anonymous functions make traces harder to read, because the trace has no name to show for them. So give your callbacks names. For example, write function showItem(item) { ... } as the callback. Then the trace shows showItem.

V8 also has extra tools that are not part of the JavaScript standard, such as Error.captureStackTrace and Error.stackTraceLimit. The later lesson Stack traces & the stack trace API covers them.

The stack has a size limit. If calls keep going on top and none of them return, the stack fills up. This is called a stack overflow.

• Chrome, Node, and Safari throw RangeError: Maximum call stack size exceeded.
• Firefox may throw InternalError: too much recursion.

How many calls fit depends on the engine, the size of each frame, and the settings.

The first example uses a setter. A setter is a function that runs when code assigns to a property. Writing set name(value) { ... } inside an object means: when code writes user.name = something, run this function.

1const user = {2  set name(value) {3    this.name = value;4  }5};6try {7  user.name = "Ada";8} catch (error) {9  console.log(error.name);10}

Line 7 writes user.name = "Ada", so the setter runs. But line 3, inside the setter, writes to this.name again. That runs the same setter again, which writes again, and so on. The calls never end. The catch on line 8 catches the error, and line 9 prints its name, RangeError.

To fix it, store the value under a different name, such as this._name, or in a private field.

1function first() {2  second();3}4function second() {5  first();6}7try {8  first();9} catch (error) {10  console.log(error.name);11}

Recursion means a function that calls itself. Here, two functions take turns: first calls second, and second calls first. This is called mutual recursion. It overflows for the same reason: no call ever returns.

Line 8 starts the loop inside a try block. When the stack is full, the catch catches the error, so the page keeps working. Line 10 prints RangeError.

In the lesson Debugging in the browser, you paused code with breakpoints. A breakpoint is a line where DevTools pauses your code. You also stepped into and out of functions.

While the code is paused, DevTools shows a Call Stack panel. It is a live view of the call stack. The top entry is the function running now. The functions that called it are below.

1function checkout() {2  calculateTotal();3}4function calculateTotal() {5  applyCoupon();6}7function applyCoupon() {8  debugger;9}10checkout();

1. Open DevTools, paste the code into the Console, and press Enter.
2. The debugger; statement on line 8 pauses the code. DevTools opens the Sources panel (called Debugger in Firefox).
3. Find the Call Stack panel. It lists applyCoupon, then calculateTotal, then checkout.
4. Click each one. The Scope panel changes to show that frame's variables.

Some calls happen later, not right away. setTimeout asks the browser to run a function later. The function you hand to it is called a callback.

const logs = [];
function start() {
  logs.push("start");
  setTimeout(() => {
    logs.push("callback");
    console.log(logs.join(", "));
  }, 0);
  logs.push("end");
}
start();

1. Line 10 calls start, and line 3 adds "start" to the list.
2. Line 4 hands the callback to setTimeout. The callback doesn't run yet.
3. Line 8 adds "end". Then start returns, and its frame comes off.
4. Later, the browser calls the callback on lines 5 and 6. The start frame is gone by then, so the callback starts on an empty stack. It prints start, end, callback.

DevTools can still show which code set up the timer. This is called an async stack trace. DevTools builds that history for you. It is not one real stack, and the old frames are not still there. You will meet async stack traces again in the lesson Async stack traces.

Where you'll use this

You use the call stack whenever you debug code that jumps between helper functions. Say an error happens inside roundPrice. The stack tells you whether the bad value came from calculateTotal or from applyCoupon. Or say a callback fails inside forEach. The stack tells you which of your functions started the forEach.

The four tools below are easy to mix up. Read each row as: "use this tool when you want to know this."

When you meet an error, try these steps:

1. Find the first frame that is in your own code, and read that line.
2. Read down the stack to find which function passed in the bad value.
3. Look at the variables in that frame, instead of guessing.
4. Run the same path again with a breakpoint on the line where the value changes. Named callbacks make the path easier to follow.

The stack shows the path through your functions. It doesn't tell you whether a value is right. So use it together with a breakpoint, or a console.log of the value you care about.

Common misconceptions

function loadCart() {
  console.log("before");
  throw new Error("offline");
}
try {
  loadCart();
} catch (error) {
  console.log("caught");
}

Line 6 calls loadCart. Line 2 prints "before", and line 3 throws an error. loadCart has no catch of its own, so JavaScript removes its frame and keeps looking. It finds the catch on line 7, and line 8 prints "caught".

The stack trace saved in the error still lists loadCart. But that frame is no longer on the stack.

For each question, ask two things. Which frame is on top right now? And when does the function underneath go on? Each answer explains why it is right or wrong.

Key takeaways

• Calling a function pushes a frame onto the stack. Returning pops it off.
• The top frame is the function running now. The functions that called it wait underneath.
• A stack trace is a copy of the stack, saved when an error is made. Read it from the top down.
• A stack overflow happens when calls keep going inside calls until the stack is full.
• When code is paused, DevTools lets you click each frame to see its line and its variables.

Up next: Hoisting & the temporal dead zone.