JavaScript Asynchronous
catchhandles a rejected promise, andfinallyruns whatever happened.
An error inside a promise does not crash the program; it rejects the promise.
If nothing catches it, the browser reports an unhandled rejection.
Example
javascript
Promise.reject(new Error("no network"))
.catch(function (error) {
console.log("caught: " + error.message);
});The output is caught: no network.
catch runs when the promise, or any step before it, fails.
finally runs either way and receives no value.
Throwing inside a then rejects the promise it returns.
Syntax
javascript
promise
.then(handler)
.catch(handleError)
.finally(cleanUp);catch is shorthand for then(null, handler).
A thrown error becomes a rejection, so the catch picks it up.
Example
javascript
Promise.resolve()
.then(function () {
throw new Error("something broke");
})
.catch(function (error) {
console.log(error.message);
});The output is something broke.
It is for cleanup, like hiding a loading spinner.
It does not change the value passing through.
Example
javascript
Promise.reject("failed")
.catch(function (reason) {
console.log("handled " + reason);
})
.finally(function () {
console.log("cleaned up");
});The output is handled failed then cleaned up.
A catch only covers the steps above it.
Putting it at the end is almost always what you want.
Example
javascript
Promise.reject("early failure")
.catch(function (reason) {
return "recovered from " + reason;
})
.then(function (value) {
console.log(value);
});Because the catch came first, the then still runs.
A rejection with no catch is reported by the browser as an error.
Always end a chain with a catch.
Example
javascript
Promise.reject("ignored")
.catch(function (reason) {
console.log("handled properly: " + reason);
});Removing the catch here would log an unhandled rejection warning.
Rejecting with an Error gives a message and a stack trace.
Example
javascript
Promise.reject(new Error("bad id"))
.catch(function (error) {
console.log(error instanceof Error);
console.log(error.message);
});Rejecting with a plain string works but tells you less.
Complete Example
html
<!DOCTYPE html>
<html>
<head>
<title>JavaScript Promise Errors</title>
</head>
<body>
<h1>Promise Errors</h1>
<p id="out">Loading...</p>
<script>
function loadUser(id) {
return new Promise(function (resolve, reject) {
setTimeout(function () {
if (id > 0) {
resolve("Ada");
} else {
reject(new Error("invalid id"));
}
}, 500);
});
}
loadUser(0)
.then(function (name) {
document.getElementById("out").textContent = "Welcome, " + name;
})
.catch(function (error) {
document.getElementById("out").textContent = "Failed: " + error.message;
})
.finally(function () {
console.log("request finished");
});
</script>
</body>
</html>Run the above example in the Try It Editor.
Try a valid id:
Change loadUser(0) to loadUser(1) and watch the other branch run.
catch handles a rejection from any earlier step.finally runs either way and is for cleanup.catch only covers what comes before it.catch.Promise error handling is one catch at the end of the chain.
Rejecting with an Error object gives you far more to work with.
An unhandled rejection is a bug, not a warning to ignore.