Error handling with promises

Errors ride the chain

In the Promises lesson you learned that a promise represents one future result. The happy path is only half the story. Real networks fail, users close tabs, JSON can be malformed, and handlers can contain bugs. Promise error handling is the map that tells those failures where to go.

Keep the earlier error lessons nearby: try, catch & finally covers synchronous errors, Throwing & custom errors covers custom error classes, and Error handling strategies helps decide what should be handled locally.

Rejection propagation means the failure travels through the chain until a rejection handler appears. Fulfillment handlers are not called with an error value. They are skipped. A catch is shorthand for .then(undefined, onRejected), so it only reacts to the rejection path.

1function step(name, value, failAt) {2  console.log(name + " saw " + value);3  if (failAt === name) throw new Error(name + " broke");4  return value + " -> " + name;5}6 7Promise.resolve("order")Run8  .then((value) => step("1", value, "2"))9  .then((value) => step("2", value, "2"))10  .then((value) => step("3", value, "2"))11  .catch((error) => {12    console.log("catch fixed " + error.message);13    return "replacement order";14  })15  .then((value) => console.log("after catch: " + value));

Change which step fails and replay the trace. If nothing fails, the catch is skipped. If step 1 fails, steps 2 and 3 do not run at all. The catch receives an Error object, returns a recovery value, and the final then receives that repaired value.

A final catch is a safety net for the whole chain. A catch in the middle is a local repair station. The two-argument form .then(onOk, onFail) is sometimes useful, but it has a sharp edge: the second argument does not catch exceptions thrown by the first argument of the same then.

1Promise.resolve("file")2  .then(3    (value) => {4      console.log("onOk got " + value);5      throw new Error("onOk broke");6    },7    (error) => console.log("then onFail caught " + error.message),8  )9  .catch((error) => console.log("catch caught " + error.message));

Toggle “source rejects” and “onOk throws.” When the source promise rejects, the second argument of then can catch it. When onOk throws, the promise returned by that then rejects, so only a later handler can catch it.

const sourceRejects = false;

Promise.resolve("file")
  .then(
    (value) => {
      console.log("onOk got " + value);
      throw new Error("onOk broke");
    },
    (error) => console.log("then onFail caught " + error.message),
  )
  .catch((error) => console.log("catch caught " + error.message));

A catch handler should not treat every failure the same. Some errors are expected and recoverable: a missing profile can use a guest profile. Other errors are unknown: a network outage, a corrupt response, or a programming bug should keep traveling until code that can make a safe decision sees it.

1class NotFoundError extends Error {}2 3function readUser(kind) {4  if (kind === "not-found") throw new NotFoundError("missing user");5  if (kind === "network") throw new Error("network down");6  throw new SyntaxError("bad JSON");7}8 9Promise.resolve()Run10  .then(() => readUser("not-found"))11  .catch((error) => {12    if (error instanceof NotFoundError) {13      return { name: "Guest" };14    }15    throw error;16  })17  .then(18    (user) => console.log("loaded " + user.name),19    (error) => console.log("still failed: " + error.message),20  );

This pattern pairs naturally with custom error classes from Throwing & custom errors. Check for the error type you know how to fix. Rethrow everything else so you keep the stack trace, the message, and the original meaning.

// Prefer this:
return Promise.reject(new TypeError("id must be a number"));

// Avoid this:
return Promise.reject("id must be a number");

Rejecting with strings technically works, but Error objects are much easier to debug. They carry a message, usually a stack trace, and can be checked with instanceof.

Promise handlers convert thrown exceptions into rejections. So does a synchronous throw inside a new Promise executor. But not every throw near promise code is promise-aware. Timing matters.

function fakeFetch(id) {
  return Promise.resolve({ id, name: "Ada" });
}

function loadUser(id) {
  if (!id) throw new TypeError("id required");
  return fakeFetch(id);
}

loadUser().catch((error) => console.log(error.message));

The call to loadUser() throws before it returns. JavaScript never gets a promise object, so .catch(...) is never called. Fix it by making the function consistently promise-shaped.

async function loadUser(id) {
  if (!id) throw new TypeError("id required");
  return { id, name: "Ada" };
}

loadUser().catch((error) => console.log(error.message));

function loadUser(id) {
  if (!id) return Promise.reject(new TypeError("id required"));
  return Promise.resolve({ id, name: "Ada" });
}

loadUser().catch((error) => console.log(error.message));

checking in this browser… Feature-detect before using it; Node 22 does not include it.

ES2025 also adds Promise.try(() => loadUser()), which turns a synchronous throw into a rejection. It is covered in the next lesson, Promise combinators. It is not in every browser and is not in Node 22, so feature-detect it before use.

const promise = new Promise((resolve) => {
  setTimeout(() => {
    throw new Error("timer boom");
  }, 0);
});

promise.catch((error) => console.log("caught " + error.message));

A synchronous throw inside the executor rejects. A throw inside setTimeout happens later, after the executor has returned. That throw is an uncaught exception, and the promise above stays pending forever.

1<!doctype html>2<button id="reject">Create unhandled rejection</button>3<button id="late">Handle it late</button>4<script>5  let promise;6  function report(type, reason) {7    parent.postMessage({ lesson: "promise-errors", type, reason: String(reason && reason.message || reason) }, "*");8  }9  addEventListener("unhandledrejection", (event) => {10    event.preventDefault();11    report("unhandledrejection", event.reason);12  });13  addEventListener("rejectionhandled", () => report("rejectionhandled", "late catch attached"));14  document.getElementById("reject").addEventListener("click", () => {15    promise = Promise.reject(new Error("alarm in empty building"));16  });17  document.getElementById("late").addEventListener("click", () => {18    if (promise) promise.catch(() => {});19  });20</script>

Browsers fire unhandledrejection on window. Calling event.preventDefault() suppresses the browser’s default console report. If a handler is attached later, browsers can fire rejectionhandled. In Node.js, use process.on("unhandledRejection") for monitoring; since Node 15 the default is to throw, which crashes the process if nothing handles it.

saveDraft(article)
  .then((draft) => publishDraft(draft))
  .then((url) => showSuccess(url))
  .catch((error) => {
    reportError(error);
    showFriendlyMessage("We could not publish yet.");
  });

In application code, end a chain with a catch or return the promise to a caller that will handle it. Do not create floating promises whose failures have nowhere useful to go.

finally is for cleanup: hide a spinner, release a lock, close a menu, restore a disabled button. It receives no argument. It normally passes the original fulfillment value or rejection reason through. But if finally throws, or returns a rejected promise, that new failure replaces the old outcome.

Promise.reject(new Error("offline"))
  .finally(() => console.log("close spinner"))
  .catch((error) => console.log(error.message));

Promise.resolve("saved")
  .finally(() => {
    throw new Error("cleanup failed");
  })
  .catch((error) => console.log(error.message));

The first chain logs cleanup and still catches offline. The second chain starts fulfilled with saved, but finally throws cleanup failed, so that new error replaces the success.

Common misconceptions

• “catch stops the whole chain forever.” Returning from catch fulfills the next promise, so the chain can continue.
• “The second argument of then catches errors thrown by the first argument.” It handles rejection of the previous promise only.
• “try/catch around a promise chain catches its future rejection.” It only catches synchronous work done before the stack unwinds.
• “finally receives the value or error.” It receives no argument and is for cleanup, not transformation.
• “Unhandled rejections are harmless warnings.” They often indicate lost work; Node’s default can crash the process.
• “Rejecting with a string is just as good as an Error.” Strings lose stack traces and type checks.

Key takeaways

• A rejected promise skips fulfillment handlers until a rejection handler appears.
• .catch(f) is .then(undefined, f).
• Returning from catch recovers; throwing from catch rethrows.
• A thrown exception inside a promise handler rejects the promise that handler returned.
• Synchronous throws before a promise is returned cannot be caught by .catch.
• Always end a chain with catch or return it to a caller that handles it.

Promise error handling is the art of keeping failures on a visible path: catch what you can fix, rethrow what you cannot, and never leave the alarm unheard.

Up next: Promise combinators.