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.
Catch a rejection of promiseor 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
Parameter
Description
onRejected
A 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 Value
Description
Promise
A 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.
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.
Returning a value means recovery. The function returns 0 instead of throwing, so score fulfills with 0. Anyone using score sees a normal value.
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);
});
step 1: read the text
caught: not a number: abc
chain goes on with -1
How It Works
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.
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.
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);
});
log it: user 2 not found
show message: Profile page failed. user 2 not found
Hello, Guest
How It Works
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.
A rejected chain skips then. The then that follows would print skipped, but it only handles success, so it is passed over completely.
The second catch ends the failure. It prints the message and returns "Guest". The promise fulfills again, and the last then prints Hello, Guest.
Compatibility
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.
BaselineEvery modern browser
Google ChromeAll modern versions
Full support
Mozilla FirefoxAll modern versions
Full support
Apple SafariAll modern versions
Full support
Microsoft EdgeAll modern versions
Full support
Node.jsAll current releases
Supported
DenoAll releases
Supported
Internet ExplorerNo 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.