Error handling with promises

Errors travel along the chain

In the Promises lesson you met the promise. A promise is an object that stands for a result that isn't ready yet. Later it ends in one of two ways:

• Fulfilled: the work worked, and the promise has a value.
• Rejected: the work failed, and the promise has an error. This error is called the rejection reason.

Things fail all the time. The network drops. A user closes the tab. A server sends broken data. Your own code has a bug. This lesson shows where a failure goes in a promise chain, and how your code can deal with it.

Two words come up again and again. A handler is a function you give to a promise, to run later:

• A success handler runs when the promise is fulfilled. It is the first function you pass to .then.
• An error handler runs when the promise is rejected. It is the function you pass to .catch, or the second function you pass to .then.

Three earlier lessons help here. try, catch & finally covers errors in code that runs straight through. Throwing & custom errors covers your own error classes. Error handling strategies helps you decide which code should deal with an error.

When a promise in a chain is rejected, the error moves down the chain. JavaScript skips each success handler. It does not call them with the error. It stops at the first error handler it finds.

.catch(f) is a short way to write .then(undefined, f). It gives no success handler, only an error handler. So it only runs when there is an error.

Promise.resolve("tea")
  .then(() => {
    throw new Error("kettle broke");
  })
  .catch((error) => console.log("caught " + error.message));

Line 1 makes a promise that is already fulfilled with "tea". The .then handler on lines 2 to 4 throws an error. A .then call always gives back a new promise, and the throw rejects that new promise. So line 5's .catch runs and prints caught kettle broke.

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, then step through again:

• If no step fails, the catch on line 11 is skipped.
• If step 1 fails, steps 2 and 3 never run.
• In every failing case, the catch gets an Error object and returns "replacement order". The last .then on line 15 gets that new value.

Each handler gives back a new promise. What the handler does decides how that promise ends. Read each row from left to right.

Where you put an error handler decides which failures it sees:

• A .catch at the end of a chain is a safety net. It sees any failure that gets that far.
• A .catch in the middle fixes one problem, and the chain keeps going.
• .then(onOk, onFail) takes two handlers at once: onOk for success and onFail for failure.

The two-handler form has a trap. onFail does not catch an error thrown by onOk in the same .then. It only sees a failure of the promise before that .then.

Promise.reject(new Error("offline"))
  .then(
    () => console.log("success"),
    (error) => console.log("source handled: " + error.message),
  );

Promise.resolve("file")
  .then(() => {
    throw new Error("bad file");
  }, (error) => console.log("same then: " + error.message))
  .catch((error) => console.log("later catch: " + error.message));

The first chain starts with a rejected promise, so its second handler, onFail, runs and prints source handled: offline. The second chain starts with a fulfilled promise. Its first handler throws bad file. The second handler in the same .then doesn't see that error. The later .catch on line 11 does, and prints later catch: bad file.

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

The first button makes the first promise fulfill or reject. The second makes onOk throw or return. The other buttons choose where the error handler goes. Then press Run. When the first promise rejects, onFail catches it. When onOk throws, the promise from that .then is rejected, so only a handler further down 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));

Each row is one place to put an error handler. Read across to see when to use it and what to watch out for.

A .catch handler should not treat every error the same way. Some errors are expected, and you know how to fix them. For example, if a user profile is missing, you can show a guest profile instead.

Other errors are a surprise: the network is down, the data is broken, or there is a bug. For those, rethrow the error. Rethrowing means throwing the same error again, so it keeps moving down the chain. Later code that knows more can then decide what to do.

Promise.reject(new TypeError("bad id"))
  .catch((error) => {
    if (error instanceof RangeError) return "fallback";
    throw error;
  })
  .catch((error) => console.log(error.name + ": " + error.message));

Line 1 makes a promise rejected with a TypeError. On line 3, instanceof checks the error's type: error instanceof RangeError is true only if the error is a RangeError. This one is a TypeError, so line 4 throws the same error again. The second .catch prints TypeError: bad id.

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()10  .then(() => readUser("not-found"))Run11  .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 works well with the error classes from Throwing & custom errors. Check for the error type you know how to fix. Throw every other error again. That keeps its message, its type, and its stack trace: the list of function calls that led to the error.

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

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

Promise.reject(reason) makes a promise that is already rejected with that reason. You can reject with plain text, but an Error object is much easier to debug. It has a message and usually a stack trace, and you can check its type with instanceof.

A throw inside a promise handler becomes a rejection. So does a throw inside the executor: the function you pass to new Promise(...), which runs right away. But not every throw near promise code becomes a rejection. It depends on when the throw happens.

function request(url) {
  if (url === "/offline") return Promise.reject(new TypeError("network failed"));
  return Promise.resolve({ ok: false, status: 404 });
}

request("/offline").catch((error) => console.log(error.message));
request("/missing").then((response) => console.log(response.status + " is a response"));

This small request function copies how fetch behaves. fetch is the browser's built-in way to ask a server for data:

• If the network fails, the promise is rejected. Line 6's .catch prints network failed.
• If the server answers "404, not found", the promise is still fulfilled. The answer has ok: false. Line 7 prints 404 is a response.

So real code checks response.ok, and throws an error itself when the answer is not OK.

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

On line 10, loadUser() runs first. No id is passed, so line 6 throws right away. The function never returns a promise, so JavaScript never reaches .catch(...), and the error goes uncaught. To fix it, make the function always return a promise, even when it fails:

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

An async function always returns a promise. If it throws, that promise is rejected. Fix 2 does the same thing by hand with Promise.reject. Both print id required.

Checking this browser… Check that it exists before you use it; Node 22 doesn't have it.

A newer tool, Promise.try(() => loadUser()), also turns a throw into a rejected promise. It was added in ES2025, the 2025 edition of JavaScript. The next lesson, Promise combinators, covers it. Not every browser has it yet, and Node 22 doesn't, so check that it exists before you use it.

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

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

A throw inside the executor itself rejects the promise. But setTimeout runs its function later, after the executor has finished. So the throw on line 3 is an uncaught error, not a rejection. The .catch on line 7 never runs, and the promise stays pending (not finished) forever.

An unhandled rejection is a promise that was rejected while no error handler was attached to it.

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>

Here is what each tool does:

• The browser fires an unhandledrejection event on window. An event is a message your code can listen for.
• Calling event.preventDefault() stops the browser from printing its usual error in the console.
• If a handler is attached later, the browser can fire rejectionhandled.
• In Node.js, listen with process.on("unhandledRejection"). Since Node 15, an unhandled rejection with no listener stops the whole program.

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

This chain saves a draft, publishes it, and shows the link. The .catch at the end reports any failure and shows the user a friendly message. In your own code, always do one of two things: end the chain with a .catch, or return the promise to the code that called you, so it can handle it. A promise that does neither is called a floating promise: if it fails, the error has nowhere useful to go.

.finally(f) runs f when the promise ends, whether it was fulfilled or rejected. Use it for cleanup, such as hiding a loading spinner, closing a menu, or turning a button back on. Here is how it behaves:

• f gets no value and no error.
• Usually, the original value or error passes straight through to the next handler.
• But if f throws, or returns a rejected promise, that new error takes the place of the old result.

Promise.resolve("saved")
  .finally(() => console.log("cleanup"))
  .then((value) => console.log("value " + value));

Line 2 prints cleanup first. Its function returns nothing, but that doesn't replace "saved". Line 3 still gets the original value and prints value saved.

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 prints close spinner, then its .catch still gets the offline error. The second chain starts fulfilled with "saved". But its finally throws cleanup failed, so that new error replaces the success, and the .catch prints it. The two chains take turns, one step at a time. The first chain needs a few extra steps to pass its error through finally, so the console shows close spinner, cleanup failed, then offline.

Common mix-ups

• "catch ends the whole chain." No. When a .catch handler returns, the next promise is fulfilled, so the chain keeps going.
• "The second handler of then catches errors from the first handler." No. It only catches a failure of the promise before that .then.
• "A try/catch around a promise chain catches its later rejections." No. It only catches errors thrown while the code inside it is running right now.
• "finally gets the value or the error." No. It gets nothing. It is for cleanup, not for changing the result.
• "Unhandled rejections are harmless warnings." No. They often mean work was lost, and by default Node.js stops the program.
• "Rejecting with plain text is as good as an Error." No. Plain text has no stack trace, and you can't check its type with instanceof.

Key takeaways

• A rejected promise skips every success handler until it reaches an error handler.
• .catch(f) is a short way to write .then(undefined, f).
• Returning from .catch fixes the chain. Throwing from .catch passes the error on.
• A throw inside a promise handler rejects the promise that the handler's .then or .catch gives back.
• A throw that happens before a promise is returned can't be caught by .catch.
• Always end a chain with .catch, or return it to code that will handle it.

In one line: keep every failure on a path someone can see. Fix the errors you know, throw the rest again, and never leave a rejection unhandled.

Up next: Promise combinators.