The catch() method returns a Promise
and deals with rejected cases only. It behaves the same as calling Promise.prototype.then(undefined, onRejected)
(in fact, calling obj.catch(onRejected)
internally calls obj.then(undefined, onRejected)
).
Syntax
p.catch(onRejected); p.catch(function(reason) { // rejection });
Parameters
- onRejected
- A
Function
called when thePromise
is rejected. This function has one argument:reason
- The rejection reason.
catch()
is rejected ifonRejected
throws an error or returns a Promise which is itself rejected; otherwise, it is resolved.
Return value
Internally calls Promise.prototype.then
on the object upon which is called, passing the parameters undefined
and the onRejected
handler received; then returns the value of that call (which is a Promise
).
Demonstration of the internal call:
// overriding original Promise.prototype.then/catch just to add some logs (function(Promise){ var originalThen = Promise.prototype.then; var originalCatch = Promise.prototype.catch; Promise.prototype.then = function(){ console.log('> > > > > > called .then on %o with arguments: %o', this, arguments); return originalThen.apply(this, arguments); }; Promise.prototype.catch = function(){ console.log('> > > > > > called .catch on %o with arguments: %o', this, arguments); return originalCatch.apply(this, arguments); }; })(this.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()]
Description
The catch
method can be useful for error handling in your promise composition.
Examples
Using and chaining the catch
method
var p1 = new Promise(function(resolve, reject) { resolve('Success'); }); p1.then(function(value) { console.log(value); // "Success!" throw 'oh, no!'; }).catch(function(e) { console.log(e); // "oh, no!" }).then(function(){ console.log('after a catch the chain is restored'); }, function () { console.log('Not fired due to the catch'); }); // The following behaves the same as above p1.then(function(value) { console.log(value); // "Success!" return Promise.reject('oh, no!'); }).catch(function(e) { console.log(e); // "oh, no!" }).then(function(){ console.log('after a catch the chain is restored'); }, function () { console.log('Not fired due to the catch'); });
Gotchas when throwing errors
// Throwing an error will call the catch method most of the time var p1 = new Promise(function(resolve, reject) { throw 'Uh-oh!'; }); p1.catch(function(e) { console.log(e); // "Uh-oh!" }); // Errors thrown inside asynchronous functions will act like uncaught errors var p2 = new Promise(function(resolve, reject) { setTimeout(function() { throw 'Uncaught Exception!'; }, 1000); }); p2.catch(function(e) { console.log(e); // This is never called }); // Errors thrown after resolve is called will be silenced var p3 = new Promise(function(resolve, reject) { resolve(); throw 'Silenced Exception!'; }); p3.catch(function(e) { console.log(e); // This is never called });
If it is resolved
//Create a promise which would not call onReject var p1 = Promise.resolve("calling next"); var p2 = p1.catch(function (reason) { //This is never called console.log("catch p1!"); console.log(reason); }); p2.then(function (value) { console.log("next promise's onFulfilled"); /* next promise's onFulfilled */ console.log(value); /* calling next */ }, function (reason) { console.log("next promise's onRejected"); console.log(reason); });
Specifications
Specification | Status | Comment |
---|---|---|
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'Promise.prototype.catch' in that specification. |
Standard | Initial definition in an ECMA standard. |
ECMAScript Latest Draft (ECMA-262) The definition of 'Promise.prototype.catch' in that specification. |
Draft |
Browser compatibility
To contribute to this compatibility data, please write a pull request against this repository: https://github.com/mdn/browser-compat-data.
Feature | Chrome | Firefox | Edge | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic Support | 32.0 | 29.0 | (Yes) | (No) | 19 | 7.1 |
Feature | Android | Chrome for Android | Edge mobile | Firefox for Android | IE mobile | Opera Android | iOS Safari |
---|---|---|---|---|---|---|---|
Basic Support | 4.4.4 | 32.0 | (Yes) | 29 | (No) | (Yes) | 8.0 |
See also
Document Tags and Contributors
Tags:
Contributors to this page:
fscholz,
amm0nium,
ParaBolt,
SheltonDong,
kdex,
Granjow,
torazaburo,
joshunger,
eduardoboucas,
UziTech,
idrism,
Brettz9,
flockonus,
fskuok,
realityking
Last updated by:
fscholz,