---
hide_title: false
hide_table_of_contents: false
pagination_next: null
pagination_prev: null
---
# Promise.prototype.catch()

The **`catch()`** method of a `Promise` object schedules a function to be called when the promise is rejected. It immediately returns an equivalent `Promise` object, allowing you to [chain](https://developer.mozilla.org/docs/Web/JavaScript/Guide/Using_promises#chaining) calls to other promise methods. It is a shortcut for [`Promise.prototype.then(undefined, onRejected)`](../../../globals/Promise/prototype/then.mdx).

## Syntax

```js
catch(onRejected)

catch((reason) => {
  // rejection handler
})
```

### Parameters

- `onRejected`
  - : A `Function` called when the `Promise` is rejected. This function has one parameter: the _rejection reason_.

### Return value

Returns a new `Promise`. This new promise is always pending when returned, regardless of the current promise's status. It's eventually rejected if `onRejected` throws an error or returns a Promise which is itself rejected; otherwise, it's eventually fulfilled.

## Description

The `catch` method is used for error handling in promise composition. Since it returns a `Promise`, it [can be chained](https://developer.mozilla.org/docs/Web/JavaScript/Guide/Using_promises#chaining_after_a_catch) in the same way as its sister method, [`Promise.prototype.then()`](../../../globals/Promise/prototype/then.mdx).

If a promise becomes rejected, and there are no rejection handlers to call (a handler can be attached through any of [`Promise.prototype.then`](../../../globals/Promise/prototype/then.mdx), [`Promise.prototype.catch`](../../../globals/Promise/prototype/catch.mdx), or [`Promise.prototype.finally`](../../../globals/Promise/prototype/finally.mdx)), then the rejection event is surfaced by the host. In the browser, this results in an [`unhandledrejection`](https://developer.mozilla.org/docs/Web/API/Window/unhandledrejection_event) event. If a handler is attached to a rejected promise whose rejection has already caused an unhandled rejection event, then another [`rejectionhandled`](https://developer.mozilla.org/docs/Web/API/Window/rejectionhandled_event) event is fired.

`catch()` internally calls `then()` on the object upon which it was called, passing `undefined` and `onRejected` as arguments. The value of that call is directly returned. This is observable if you wrap the methods.

```js
// 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 promise
Promise.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 passing `undefined` still causes the returned promise to be rejected, and you have to pass a function to prevent the final promise from being rejected.

Because `catch()` just calls `then()`, it supports subclassing.

> **Note:** The examples below are throwing instances of [`Error`](../../../globals/Error/Error.mdx). As with synchronous [`throw`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/throw) 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.
