Error handling

What it is and why it exists

Error handling is the control-flow protocol for operations that cannot produce their normal result. A function throws a value instead of returning, and JavaScript transfers control to the nearest matching catch. If no handler exists in the current call chain, the exception reaches the host environment.

An Error object is the conventional failure value. Its standardized data includes name, message, and optional cause; runtimes also commonly expose a non-standard stack for diagnostics. Built-in subclasses such as TypeError, RangeError, ReferenceError, and SyntaxError distinguish broad language-level failure categories.

JavaScript technically permits throw with any value. That flexibility is why a catch binding must be treated as unknown until inspected. Throwing an Error is still the useful application contract because it carries type, context, and usually a stack trace in a shape that tools and humans recognize.

Failed operations, not ordinary branches

Use an exception when an operation cannot honor its contract and its immediate caller may not know the recovery policy. Invalid configuration syntax, a broken invariant, or a failed dependency call fit that model. A normal and expected alternative, such as “no search match,” is often clearer as undefined, null, or an explicit result object.

The distinction depends on the API contract, not on how often an event occurs. A missing record can be an expected query result in one layer and a failed requirement in another. Translate between those meanings at the boundary that owns the policy instead of making every low-level function decide how the user should be notified.

Four decisions at every catch boundary

A useful handler makes an explicit decision: recover with a documented value, retry under a bounded policy, translate the failure while preserving its cause, or perform local work and rethrow. Logging alone is not recovery. Catching an error and then continuing with an invented value silently changes the function’s contract.

Keep a try region as small as the policy allows. A broad block can accidentally classify a programming bug from later code as an expected input or dependency failure. Narrow regions also make it obvious which operation a handler is describing.

How it works

Throwing and stack unwinding

Evaluating throw value creates an abrupt completion. JavaScript stops the remaining statements in that block and searches outward through active calls for a catch. This error propagation preserves the thrown value; it does not automatically convert strings, objects, or other values into Error instances.

When a handler is found, its binding receives the exact thrown value. Execution continues after the entire try...catch...finally statement if the handler completes normally. If the handler rethrows, the search resumes farther out with that new or original value.

The diagram has two entry points into failure handling. A synchronous throw unwinds the current calls immediately. A rejected Promise reports failure through its settlement state, so a later await or rejection handler creates the point where normal exception-style control flow resumes.

The roles of try, catch, and finally

The try block contains the operation governed by one handling policy. The catch block is optional when finally is present, and its parameter can be omitted when the value is not needed. Conditional catches do not have special syntax; inspect the value, handle the cases you own, and rethrow everything else.

The finally block runs before control leaves the construct, whether the earlier path completed normally, returned, broke from a loop, or threw. It is the right place to release resources or restore local state. It is not a process-shutdown guarantee: forced termination can prevent JavaScript from executing more code.

A return or throw inside finally replaces the completion already in progress. That means it can discard both a valid return value and an active exception. Cleanup code should normally finish without changing control flow, allowing the original outcome to survive.

Promise rejection is a separate channel

An async function always returns a Promise. Throwing anywhere in its body rejects that Promise, including a throw before its first await. A caller handles the failure by awaiting the Promise inside try...catch, returning it to another owner, or attaching a rejection handler.

Calling an async function inside a try block without await does not connect its later rejection to that catch. The call itself successfully produces a Promise, then the Promise settles after synchronous control has left the block. The missing ownership often appears as an unhandled rejection rather than the intended recovery path.

Promise chains follow the same idea. A throw in a .then() callback rejects the Promise returned by that .then(), and .catch(handler) is shorthand for a rejection handler. If a handler returns normally, the next Promise is fulfilled with its return value; to keep the chain failed, the handler must throw or return a rejected Promise.

Errors should cross ownership boundaries

Low-level code should normally attach facts it knows and let its caller decide presentation. A parser can identify an invalid field; an HTTP handler can map that domain error to a status and public message. Mixing both decisions produces error classes tied to one interface and makes the same domain operation hard to reuse.

The boundary that starts asynchronous work also owns its rejection. Await it, return it, put it in an explicitly managed group, or attach a terminal handler that records the deliberate fire-and-forget policy. Merely creating a Promise is not an ownership strategy.

Examples

Validate at the input boundary

This boundary distinguishes malformed JSON from a valid object with an invalid business field. It handles both known cases and rethrows anything outside its policy. The custom class gives callers a stable type and field instead of requiring them to parse a message.

JSON.parse() throws a runtime SyntaxError, so this handler can observe it. A syntax error that prevents the surrounding script from being parsed is different: none of that script runs, so a try statement inside it cannot handle the parse failure.

Add operation context without losing the cause

The lower layer knows that a connection closed; the order layer knows which operation failed. Error wrapping records both facts. Passing the caught value as cause keeps it available for diagnosis without placing unstable low-level wording in the public message.

class OrderLoadError extends Error {
  constructor(orderId, options) {
    super(`Could not load order ${orderId}`, options);
    this.name = "OrderLoadError";
    this.orderId = orderId;
  }
}

async function requestOrder() {
  throw new TypeError("connection closed");
}

async function loadOrder(orderId) {
  try {
    return await requestOrder(orderId);
  } catch (cause) {
    throw new OrderLoadError(orderId, { cause });
  }
}

async function main() {
  try {
    await loadOrder("A-17");
  } catch (error) {
    console.log(`${error.name}: ${error.message}`);
    console.log(`cause: ${error.cause.name}: ${error.cause.message}`);
  }
}

main().catch(console.error);

OrderLoadError: Could not load order A-17
cause: TypeError: connection closed

The await inside loadOrder() matters. Returning requestOrder(orderId) directly from the try would let the function leave before the returned Promise rejects, so this local catch would not wrap the failure. return await is purposeful at a boundary that must transform a rejection.

Release a resource while preserving failure

Acquisition happens before the protected operation, and finally releases the lock on every exit from that operation. The caller still receives the original write error. The output also proves that cleanup runs before the outer handler resumes.

class Lock {
  constructor(key) {
    this.key = key;
    console.log(`acquired: ${key}`);
  }

  release() {
    console.log(`released: ${this.key}`);
  }
}

async function saveInvoice(invoiceId) {
  const lock = new Lock(`invoice:${invoiceId}`);
  try {
    throw new Error("write failed");
  } finally {
    lock.release();
  }
}

async function main() {
  try {
    await saveInvoice(42);
  } catch (error) {
    console.log(`handled: ${error.message}`);
  }
}

main().catch(console.error);

acquired: invoice:42
released: invoice:42
handled: write failed

If both the protected operation and cleanup throw, ordinary finally semantics expose the cleanup error and replace the earlier one. When both failures matter, the cleanup layer must record or aggregate them deliberately; JavaScript does not combine them automatically.

Report every outcome in a batch

Promise.allSettled() waits until each input is fulfilled or rejected and keeps the results in input order. The code retains successful task names, then turns the collected rejection reasons into one aggregate error . This policy fits a batch where all attempts should finish but the batch as a whole must still report failure.

const tasks = [
  ["catalog", () => Promise.resolve("updated")],
  ["inventory", () => Promise.reject(new Error("inventory unavailable"))],
  ["receipt", () => Promise.resolve("sent")],
];

async function runBatch(entries) {
  const settled = await Promise.allSettled(
    entries.map(([, run]) => run()),
  );
  const fulfilled = [];
  const failures = [];

  settled.forEach((result, index) => {
    const [name] = entries[index];
    if (result.status === "fulfilled") {
      fulfilled.push(name);
    } else {
      failures.push(result.reason);
    }
  });

  console.log(`fulfilled: ${fulfilled.join(",")}`);
  if (failures.length > 0) {
    throw new AggregateError(failures, `${failures.length} task failed`);
  }
}

runBatch(tasks).catch((error) => {
  console.log(`${error.name}: ${error.message}`);
  console.log(`causes: ${error.errors.map((item) => item.message).join(",")}`);
});

fulfilled: catalog,receipt
AggregateError: 1 task failed
causes: inventory unavailable

Each rejection reason can still be any JavaScript value. Production aggregation should normalize or inspect reasons before reading .message, especially when tasks call code that the batch owner does not control.

Pitfalls

Swallowing failures

Fix: recover only when the fallback is part of the function’s documented contract. For other cases, add useful context and rethrow, or rethrow the original error after any required local reporting.

Assuming every caught value is an Error

Fix: narrow the value with error instanceof Error before using Error properties. At an external boundary, normalize a non-error value once into a new Error whose cause retains the original value.

Losing a rejection by omitting await

Fix: await the operation when this scope owns its handling policy, or return the Promise so the caller owns it. For deliberate background work, attach a terminal rejection handler and document shutdown, cancellation, and observability behavior.

Returning from finally

Fix: keep finally focused on cleanup and let it complete normally. If cleanup itself can fail, define which failure wins or create an aggregate that makes both available instead of relying on accidental precedence.

Treating Promise.all() as cancellation

Fix: choose failure topology explicitly. Use allSettled() when every result matters, or give cancellable operations a shared cancellation signal when one failure should stop their work; still await settlement so cleanup has a clear owner.

Further reading

• ECMAScript language specification: the try statement
• MDN: Error
• MDN: try...catch
• MDN: Promise.allSettled()
• MDN: AggregateError
• Node.js 24: Errors