Promise.prototype.catch()

BaselineWidely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Thecatch() method ofPromise instances schedules a function to be called when the promise is rejected. It immediately returns anotherPromise object, allowing you tochain calls to other promise methods. It is a shortcut forthen(undefined, onRejected).

Try it

const promise1 = new Promise((resolve, reject) => {  throw new Error("Uh-oh!");});promise1.catch((error) => {  console.error(error);});// Expected output: Error: Uh-oh!

Syntax

promiseInstance.catch(onRejected)

Parameters

onRejected

A function to asynchronously execute when this promise becomes rejected. Its return value becomes the fulfillment value of the promise returned bycatch(). The function is called with the following arguments:

reason: The value that the promise was rejected with.

Return value

Returns a newPromise. This new promise is always pending when returned, regardless of the current promise's status. IfonRejected is called, the returned promise will resolve based on the return value of this call, or reject with the thrown error from this call. If the current promise fulfills,onRejected is not called and the returned promise fulfills to the same value.

Description

Thecatch method is used for error handling in promise composition. Since it returns aPromise, itcan be chained in the same way as its sister method,then().

If a promise becomes rejected, and there are no rejection handlers to call (a handler can be attached through any ofthen(),catch(), orfinally()), then the rejection event is surfaced by the host. In the browser, this results in anunhandledrejection event. If a handler is attached to a rejected promise whose rejection has already caused an unhandled rejection event, then anotherrejectionhandled event is fired.

catch() internally callsthen() on the object upon which it was called, passingundefined andonRejected as arguments. The value of that call is directly returned. This is observable if you wrap the methods.

// overriding original Promise.prototype.then/catch just to add some logs((Promise) => {  const originalThen = Promise.prototype.then;  const originalCatch = Promise.prototype.catch;  Promise.prototype.then = function (...args) {    console.log("Called .then on %o with arguments: %o", this, args);    return originalThen.apply(this, args);  };  Promise.prototype.catch = function (...args) {    console.error("Called .catch on %o with arguments: %o", this, args);    return originalCatch.apply(this, args);  };})(Promise);// calling catch on an already resolved promisePromise.resolve().catch(function XXX() {});// Logs:// Called .catch on Promise{} with arguments: Arguments{1} [0: function XXX()]// Called .then on Promise{} with arguments: Arguments{2} [0: undefined, 1: function XXX()]

This means that passingundefined still causes the returned promise to be rejected, and you have to pass a function to prevent the final promise from being rejected.

Becausecatch() just callsthen(), it supports subclassing.

Note:The examples below are throwing instances ofError. As with synchronousthrow statements, this is considered a good practice; otherwise, the part doing the catching would have to perform checks to see if the argument was a string or an error, and you might lose valuable information such as stack traces.

Examples

Using and chaining the catch() method

const p1 = new Promise((resolve, reject) => {  resolve("Success");});p1.then((value) => {  console.log(value); // "Success!"  throw new Error("oh, no!");})  .catch((e) => {    console.error(e.message); // "oh, no!"  })  .then(    () => console.log("after a catch the chain is restored"), // "after a catch the chain is restored"    () => console.log("Not fired due to the catch"),  );// The following behaves the same as abovep1.then((value) => {  console.log(value); // "Success!"  return Promise.reject(new Error("oh, no!"));})  .catch((e) => {    console.error(e); // Error: oh, no!  })  .then(    () => console.log("after a catch the chain is restored"), // "after a catch the chain is restored"    () => console.log("Not fired due to the catch"),  );

Gotchas when throwing errors

Throwing an error will call thecatch() method most of the time:

const p1 = new Promise((resolve, reject) => {  throw new Error("Uh-oh!");});p1.catch((e) => {  console.error(e); // "Uh-oh!"});

Errors thrown inside asynchronous functions will act like uncaught errors:

const p2 = new Promise((resolve, reject) => {  setTimeout(() => {    throw new Error("Uncaught Exception!");  }, 1000);});p2.catch((e) => {  console.error(e); // This is never called});

Errors thrown afterresolve is called will be silenced:

const p3 = new Promise((resolve, reject) => {  resolve();  throw new Error("Silenced Exception!");});p3.catch((e) => {  console.error(e); // This is never called});

catch() is not called if the promise is fulfilled

// Create a promise which would not call onRejectconst p1 = Promise.resolve("calling next");const p2 = p1.catch((reason) => {  // This is never called  console.error("catch p1!");  console.error(reason);});p2.then(  (value) => {    console.log("next promise's onFulfilled");    console.log(value); // calling next  },  (reason) => {    console.log("next promise's onRejected");    console.log(reason);  },);