JavaScript Promise catch() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Instance method

Definition

promise.catch(onRejected) runs your function when a promise rejects, that is, when something went wrong. It also catches an error thrown inside an earlier then() callback. It is a shortcut for promise.then(undefined, onRejected), and it returns a new promise. If your function returns a value, the chain recovers. If it throws again, the chain stays rejected.

Remember
promise.catch(onRejected)
  same as  promise.then(undefined, onRejected)

onRejected returns a value → chain recovers
onRejected throws          → chain stays rejected
earlier then() throws      → arrives here too

Syntax

Call catch on a promise, usually at the end of a chain, and pass one function. It receives the reason for the rejection.

JavaScript
promise.catch(onRejected)

promise
  .then(step1)
  .then(step2)
  .catch(handleError)
CallWhat it does
promise.catch(onRejected)Run onRejected(reason) if the promise rejects.
promise.then(a).catch(b)Catch a rejection of promise or an error thrown inside a.

Built into JavaScript since ES2015. A promise can reject with any value, but Error objects are best.

Library declarations
JavaScript
promise.catch(onRejected)   // returns a new Promise
// onRejected(reason) runs if the promise rejects

Parameters

ParameterDescription
onRejectedA function called with the rejection reason. If it returns normally, the new promise fulfills with the returned value. If it throws, the new promise rejects.

Return Value

Return ValueDescription
PromiseA new promise. A fulfilled value passes through untouched. After a rejection it fulfills with the return value of onRejected, or rejects if that function throws.

JavaScript Examples

Example 1 — Recover with a Fallback Value

Loading a score fails. The handler logs the problem and returns 0, so the program still works.

JavaScript
function loadScore() {
  return Promise.reject(new Error("network is down"));
}

const score = loadScore().catch((error) => {
  console.log("Problem: " + error.message);
  return 0;
});

console.log(score instanceof Promise);

score.then((value) => {
  console.log("Score is " + value);
});
Try It Yourself

How It Works

  1. The reason arrives as an argument. loadScore() gives a rejected promise, so catch calls your function with the Error object and it prints Problem: network is down.
  2. Returning a value means recovery. The function returns 0 instead of throwing, so score fulfills with 0. Anyone using score sees a normal value.
  3. catch() hands back a promise. score instanceof Promise is true, so the final then can chain on and print Score is 0. The first line prints early because it is not a callback.

Example 2 — One catch Guards the Whole Chain

A step in the middle of a chain throws an error. Watch which steps are skipped and where the chain picks up again.

JavaScript
function readAge(text) {
  const age = Number(text.trim());
  if (Number.isNaN(age)) {
    throw new Error("not a number: " + text.trim());
  }
  return age;
}

Promise.resolve("  abc ")
  .then((text) => {
    console.log("step 1: read the text");
    return readAge(text);
  })
  .then((age) => {
    console.log("step 2: age is " + age);
    return age + 1;
  })
  .catch((error) => {
    console.log("caught: " + error.message);
    return -1;
  })
  .then((result) => {
    console.log("chain goes on with " + result);
  });
Try It Yourself

How It Works

  1. A throw becomes a rejection. Inside a then callback, readAge throws because "abc" is not a number. JavaScript does not crash. It turns the error into a rejected promise.
  2. Steps in the middle are skipped. Step 2 never prints. A rejected promise slides past every then that has no failure function until it meets a catch.
  3. The chain continues after the catch. The handler prints the message and returns -1. The last then runs normally and receives that -1.

Example 3 — Rethrow an Error or Recover from It

A catch handler can throw again to keep the failure, or return a value to end it. Here is one of each.

JavaScript
function findUser(id) {
  if (id === 1) {
    return Promise.resolve("Asha");
  }
  return Promise.reject(new Error("user " + id + " not found"));
}

findUser(2)
  .catch((error) => {
    console.log("log it: " + error.message);
    throw new Error("Profile page failed. " + error.message);
  })
  .then((name) => {
    console.log("skipped, name is " + name);
  })
  .catch((error) => {
    console.log("show message: " + error.message);
    return "Guest";
  })
  .then((name) => {
    console.log("Hello, " + name);
  });
Try It Yourself

How It Works

  1. Log it, then throw again. The first catch only wants to record the problem. It ends with throw, so the promise stays rejected, now with a clearer message.
  2. A rejected chain skips then. The then that follows would print skipped, but it only handles success, so it is passed over completely.
  3. The second catch ends the failure. It prints the message and returns "Guest". The promise fulfills again, and the last then prints Hello, Guest.

Browser & Runtime Support

Promise.prototype.catch() is part of ES2015 (ES6), together with the Promise constructor and then().

✓ Baseline · ES2015

Promise.prototype.catch()

Supported in every modern browser, plus Node.js, Deno, and Bun. Internet Explorer has no native Promise.

Baseline Every modern browser
Google Chrome All modern versions
Full support
Mozilla Firefox All modern versions
Full support
Apple Safari All modern versions
Full support
Microsoft Edge All modern versions
Full support
Node.js All current releases
Supported
Deno All releases
Supported
Internet Explorer No native support
Not supported
catch() Excellent

Bottom line: Safe everywhere today. Only very old browsers such as Internet Explorer need a polyfill.

Frequently Asked Questions

It runs your function when the promise is rejected, or when an earlier then() callback in the chain throws. The function receives the reason.
Yes. catch(fn) is a shortcut for then(undefined, fn). Both return a new promise and only run fn when the promise is rejected.
Write throw error inside the catch function, or throw a new Error that explains more. The promise from catch() stays rejected, and the next catch down the chain receives it.
Yes, if the catch comes later in the same chain. The error rejects that step, and the rejection travels down to the next catch. Errors in a separate timer callback are not part of the chain.
A rejected promise with no handler is an unhandled rejection. Node.js 15 and newer ends the program with an error, and browsers print a console error.

Next: finally()

Run cleanup code after a promise succeeds or fails, without changing its result.

finally() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful