Exceptions & unwinding

What happens after a throw

You already know try/catch. You put code inside try. If that code throws an error, the catch part runs. Earlier lessons showed how to make and handle errors: custom errors, error strategies, promise errors, and reading errors.

This lesson shows what the JavaScript engine does after a throw. The engine is the program that runs your code. Chrome and Node use an engine called V8.

A stack frame is the record of one function call that is still running. The stack frames lesson shows what a frame holds. Frames sit on the call stack. Each new call goes on top. It comes off again when the function ends.

A throw stops the current line at once. The engine then has to find code that can deal with the error. On the way, it must still run every finally block it passes.

This lesson comes after Suspending frames: generators & async functions, because await changes where an error comes back. Next comes Why garbage collection?, which moves from the call stack to memory.

Before V8 runs a function, it turns it into bytecode. Bytecode is a list of small, simple steps that the engine runs one by one. Each step has a number, called its offset.

A handler table is a list the engine keeps next to that bytecode. Each row says: "if a step in this range throws, jump to this step." The step it jumps to is the handler: the start of the catch or finally code.

When nothing goes wrong, the engine never reads the table. It reads it only when code leaves a try block early. A throw does that. So does a return that has to pass through a finally first.

1function handlerTableProbe(input) {2  try {3    if (input < 0) throw new Error("negative");4    return input + 1;5  } catch (error) {6    return 0;7  } finally {8    input += 1;9  }10}11 12handlerTableProbe(1);

The lesson test runs this function in Node with two options. --print-bytecode prints the bytecode. --print-bytecode-filter=handlerTableProbe limits it to this one function. The function doesn't call console.log, so its own output can't mix with V8's list.

The test checks only the parts that stay the same from run to run:

• The Node version starts with v22.
• The V8 version starts with 12.4.
• The list contains the Handler Table heading, line 4 below.

1$ node --print-bytecode --print-bytecode-filter=handlerTableProbe handler-table-probe.mjs2[generated bytecode for function: handlerTableProbe]3...4Handler Table (size = N)5# Each row: if a step in this range throws, jump to this step. Step numbers change between V8 versions.

Each row of a handler table has three parts. The table below names them. Read each row as: the part, what it means, and why it matters.

The exact step numbers are V8 details. Other engines store the same information in their own way. JavaScript doesn't promise a V8-style table. It only promises that catch and finally behave as the language rules say.

Here is a checkout with three calls, one inside the next:

• placeOrder starts the order. It has a catch.
• chargeCard takes the payment. It has a finally, but no catch.
• validateUpi checks the UPI ID, a payment address used in India, such as asha@bank. It has a finally, but no catch.

The UPI ID "asha-upi" has no @, so validateUpi throws. Step through the code to watch the error move.

1const timeline = [];Run2function enter(label) { timeline.push("enter " + label); }3function leave(label) { timeline.push(label); }4 5function placeOrder(order) {6  enter("placeOrder");7  try {8    const receipt = chargeCard(order);9    return "confirmed: " + receipt;10  } catch (error) {11    return "handled in placeOrder: " + error.message;12  } finally {13    leave("placeOrder finally: unlock cart");14  }15}16 17function chargeCard(order) {18  enter("chargeCard");19  try {20    const authorization = validateUpi(order.upiId);21    return "charged " + authorization;22  } finally {23    leave("chargeCard finally: release terminal");24  }25}26 27function validateUpi(upiId) {28  enter("validateUpi");29  try {30    if (!upiId.includes("@")) {31      throw new Error("Invalid UPI ID");32    }33    return "UPI authorized";34  } finally {35    leave("validateUpi finally: close UPI session");36  }37}38 39console.log(placeOrder({ upiId: "asha-upi" }));40console.log(timeline.join(" -> "));

Watch the "top frame" label as you step. Line 31 throws inside validateUpi. Line 35 runs that function's finally, and then its call leaves the stack. chargeCard has no catch, so line 23 runs its finally, and that call leaves too. Line 11 is the first catch the error meets. There, placeOrder turns the error into a normal string.

The spec is the official rule book for JavaScript. It uses the word completion for how a statement ends. There are five kinds:

• normal: it ran to the end, sometimes with a value.
• return: it reached a return.
• throw: it threw an error.
• break: it jumped out of a loop.
• continue: it jumped to the next turn of a loop.

A finally block always runs when the code leaves its try or catch. If finally ends normally, the earlier completion goes on as before. If finally returns or throws, its new completion replaces the earlier one.

1function finallyReturnWins() {2  try {3    return "try return";4  } finally {5    return "finally return";6  }7}8 9function finallyCanSwallowThrow() {10  try {11    throw new Error("try exploded");12  } finally {13    return "finally recovered";14  }15}16 17const breakSteps = [];18outer: for (const item of ["first"]) {19  try {20    breakSteps.push("try " + item);21    break outer;22  } finally {23    breakSteps.push("finally " + item);24  }25}26 27console.log(finallyReturnWins());Run28console.log(finallyCanSwallowThrow());29console.log(breakSteps.join(" -> "));30console.log(eval("try { 1 } finally { 2 }"));

1function finallyReturnWins() {2  try {3    return "try return";4  } finally {5    return "finally return";6  }7}8 9function finallyCanSwallowThrow() {10  try {11    throw new Error("try exploded");12  } finally {13    return "finally recovered";14  }15}16 17const breakSteps = [];18outer: for (const item of ["first"]) {19  try {20    breakSteps.push("try " + item);21    break outer;22  } finally {23    breakSteps.push("finally " + item);24  }25}26 27console.log(finallyReturnWins());28console.log(finallyCanSwallowThrow());29console.log(breakSteps.join(" -> "));30console.log(eval("try { 1 } finally { 2 }"));

The last line is a surprise. eval runs a string as code and gives back the value of the last statement it ran. eval("try { 1 } finally { 2 }") gives 1, not 2.

The finally block did work out 2. But it ended normally, so it doesn't replace anything. The spec's rule is: when finally ends normally, keep the result of the try block. That result is 1.

1function scenario(tryAction, catchAction, finallyAction) {2  try {3    if (tryAction === "throw") throw new Error("try threw");4    if (tryAction === "return") return "try returned";5  } catch (error) {6    if (catchAction === "throw") throw new Error("catch threw");7    if (catchAction === "return") return "catch returned";8  } finally {9    if (finallyAction === "throw") throw new Error("finally threw");10    if (finallyAction === "return") return "finally returned";11  }12  return "normal completion";13}

Use the playground to try each mix. Pick nothing, return, or throw for each block. You'll see three rules:

• If try returns and finally does nothing, the try return wins.
• If finally returns or throws, finally wins.
• If try throws and catch returns, the catch return wins, unless finally replaces it.

V8 makes busy functions faster by turning them into fast machine code. This is called optimizing.

Old advice said: "never put busy code inside try/catch, because the engine can't optimize it." That was true for some older versions of V8. V8's old optimizer, Crankshaft, handled try/catch badly. In 2017, V8 replaced it with two new parts: Ignition, which runs bytecode, and TurboFan, which optimizes. Today's V8 can optimize functions that contain try, catch, and finally.

1// Tested in Node 22 (V8 12.4). Run: node --allow-natives-syntax file.mjs2function protectedAdd(x) {3  try {4    return x + 1;5  } catch (error) {6    return -1;7  } finally {8    x = 0;9  }10}11 12%PrepareFunctionForOptimization(protectedAdd);13protectedAdd(1);14protectedAdd(2);15%OptimizeFunctionOnNextCall(protectedAdd);16console.log("result", protectedAdd(3));17const status = %GetOptimizationStatus(protectedAdd);18console.log("optimized", Boolean(status & (1 << 4)));19console.log("turbo", Boolean(status & (1 << 6)));

The commands that start with % are V8 test tools, not normal JavaScript. They work only when Node starts with --allow-natives-syntax:

• %PrepareFunctionForOptimization (line 12) tells V8 to start collecting facts about the function.
• %OptimizeFunctionOnNextCall (line 15) asks V8 to optimize it on the next call.
• %GetOptimizationStatus (line 17) gives back a number. Each bit of that number answers one yes-or-no question, such as "is it optimized?"

The lesson test checks three printed lines in Node's V8 12.4: the result is 4, the optimized bit is true, and the TurboFan bit is true. So having try/catch/finally in the function did not stop V8 from optimizing it.

When you create an Error, V8 also records the list of calls that led to it. That list is the stack trace. It is saved as a string in error.stack. Error.stackTraceLimit sets how many calls V8 records.

1const normal = new Error("payment failed");2console.log(normal.stack.includes("\n    at"));3 4Error.stackTraceLimit = 0;5const withoutFrames = new Error("payment failed");6console.log(withoutFrames.stack);7console.log(withoutFrames.stack.includes("\n    at"));

Line 2 prints true, because a normal error's stack has at ... lines. Line 4 sets the limit to 0. Line 6 prints only the first line, Error: payment failed, and line 7 prints false.

The table below shows where the cost really is. Read each row as: when your code has this, this is true today, so do this.

This lesson gives no timing numbers. Timings change from machine to machine and from program to program. The safe rule is smaller: throwing is the rare path, and recording the stack trace is part of its cost. Look into it only if a profile, a recording of where your program spends its time, points there. For more on the stack string, see Stack traces & the stack trace API.

A normal try/catch covers only the call stack that is running right now. A timer callback or a promise handler runs later, after that stack is gone. So the old try can't catch their errors.

That is why the promise and async lessons use .catch, await, and host events. A host is the place where JavaScript runs: the browser or Node. Wrapping a try around the code that schedules the work is not enough.

1async function submitUpiPayment() {2  try {3    await Promise.reject(new Error("UPI gateway timeout"));4    console.log("paid");5  } catch (error) {6    console.log("caught after await:", error.message);7  }8}9 10submitUpiPayment();11console.log("after submitUpiPayment call");

Line 10 calls the function. It pauses at the await on line 3, so line 11 prints first. Then the promise rejects. The function comes back at line 3 and throws the error there, so the catch on line 5 runs.

1try {2  Promise.reject(new Error("receipt failed")).catch((error) => {3    console.log("promise handler:", error.message);4  });5  console.log("try block finished");6} catch (error) {7  console.log("caught synchronously:", error.message);8}

Line 2 makes a rejected promise and gives it its own .catch handler. Line 5 prints first. The handler runs later, after the try is done. The outer catch never runs.

1try {2  setTimeout(() => {3    try {4      throw new Error("timer failed");5    } catch (error) {6      console.log("callback handled:", error.message);7    }8  }, 0);9  console.log("try finished before timer");10} catch (error) {11  console.log("outer catch:", error.message);12}

Line 2 only schedules the callback. Line 9 prints, and the outer try ends. Later, the callback runs and throws on line 4. The try/catch inside the callback handles it.

1process.on("unhandledRejection", (reason) => {2  console.log("unhandledRejection:", reason.message);3});4 5try {6  Promise.reject(new Error("unawaited promise"));7  console.log("try block ended");8} catch (error) {9  console.log("caught:", error.message);10}11 12setTimeout(() => {}, 0);

Line 1 listens for Node's unhandledRejection event. Line 6 makes a rejected promise that nothing handles. The try on line 5 doesn't see it, so Node fires the event instead. Line 12 keeps Node running long enough for that. Browsers fire a similar event, unhandledrejection, on window.

The table below compares four cases. Read each row as: when this happens, can the try/catch around it catch the error, and what should you do?

Using this in real code

These details help you make everyday choices in code reviews. They are no reason to build your own error system, or to avoid clear error handling.

• Throw only when something truly went wrong: bad data, a broken rule, or a job this part of the code can't finish.
• Catch where you can do something useful: add details, try again, show a helpful message, or turn the error into a normal result.
• Use finally for cleanup that must run whether the code returns, throws, breaks, or continues.
• To handle a promise's error with try/catch, await the promise inside the try. Otherwise, add .catch, or return the promise to the caller.
• Measure before you change clear code for speed. If throwing shows up in a profile, throw less often on that busy path.

A real payment page might catch errors in the code that runs when you press "Pay". There it can log a custom PaymentError, show a helpful message, and use finally to hide the loading spinner. It should not use throws as the normal way to check whether every item in the cart is in stock.

Common misconceptions

• "Any try/catch stops optimization." Modern V8 can optimize code with try/catch/finally. Throwing is the slow path to measure.
• "finally always replaces the result." It always runs. But it replaces the earlier result only if it returns or throws.
• "A try around setTimeout catches errors in the callback." The callback runs later, on a new stack, after the try has ended.
• "error.stack is the live call stack." It is a string saved when the error was made, for debugging. Each engine writes it in its own way.
• "Handler tables are part of JavaScript." They are one way an engine makes the language rules work. Your code can't see them.

These four ideas sound alike. Read each row as: the idea, what it is, and what it is not.

For each question, first ask how the code ends: normally, with a return, a throw, or a break, in a timer callback, or with an awaited rejection.

Key takeaways

• In V8, a function with try/catch has a handler table. It says where to jump when a guarded line throws.
• After a throw, the engine checks the current call, runs any finally it must, and takes the call off the stack. It moves outward until a catch handles the error.
• A finally block always runs when its code is left. A return or throw in finally replaces what was happening before.
• Modern V8 can optimize functions with try/catch/finally. The slow part is throwing: making the error, recording the stack trace, and recovering.
• A normal try/catch can't catch errors in timer callbacks or in promises you don't await. await brings a rejection back into the async function.

Next, Why garbage collection? moves from the call stack to memory. You'll see how JavaScript finds objects that nothing uses any more, and frees them.