Promises and Error Handling
Weâve standardized on using promises to manage most of the asynchronous interactions in our JavaScript codebase. In addition to really enjoying the extra expressiveness and aggregation possibilities offered by promises, weâre benefitting greatly from richer error handling. Weâve had some surprises though, and this post explains some things which caught us out and some guidelines weâre following to avoid similar situations in future.
We use the excellent when.js library, however this post should be relevant no matter what implementation youâre using.
We use the excellent when.js library, however this post should be relevant no matter what implementation youâre using.
1. Reject what you would normally throw
Rejecting a promise should be synonymous with throwing an exception in synchronous code, according to Domenic Denicola. Weâve previously built some promise interfaces which can reject with no value, or with a string error message. Rejecting with a string should be discouraged for the very same reasons as throwing strings. An empty rejection is the async equivalent of throw undefined, which (hopefully) nobody would consider doing.
These practices cause us additional problems with the likes of Express and Mocha since they expect theirnext and done callbacks to be invoked with an Error instance to trigger the failure flow, otherwise they consider it a successful operation. We, quite reasonably, are in the habit of chaining promise rejections straight onto these (e.g. .then(onResolve, next) or .catch(next)). If the promise rejects with no arguments then it wonât signal a failure when used like this!Â
Guideline 1: Always reject promises with an Error instance. Do not reject with no arguments. Do not reject with non-Error objects, or primitive values.
Itâs easy to feel like rejecting a promise is less âsevereâ than throwing an exception, this impulse can lead to promises being rejected where normally you would not throw an exception (e.g. validation checks). If the above guideline is difficult to follow in a specific case because you canât think of an appropriate Error type to reject with, then perhaps it shouldnât be a rejection after all.
2. Be careful with .catch
We have been caught out with catch (a.k.a. otherwise/fail for non-ES5 browsers). The documentation for it might lead you to think that somePromise.then(onResolve).catch(onReject) is equivalent tosomePromise.then(onResolve, onReject). This appears true at a first glance:
function onResolve(result) { console.log('OK', result) }
function onReject(err) { console.log('NOT OK', err.stack) }
// This:
somePromise.then(onResolve, onReject)
// Is equivalent to:
somePromise.then(onResolve).catch(onReject)
They differ, however, in how they respond to errors thrown in callbacks. If onResolve throws and we are using the .then(onResolve, onReject) form, onReject is not invoked, and the outer promise is rejected.
var outer = resolvedPromise.then(function onResolve(result) {
throw new Error('this is an error')
}, function onReject(err) {
// Never gets invoked
})
// outer is rejected with the 'this is an error' error
If onResolve throws and we are using the .then(onResolve).catch(onReject) form, onReject is invoked, and the outer promise is resolved.
var outer = resolvedPromise.then(function onResolve(result) {
throw new Error('this is an error')
}).catch(function onReject(err) {
console.log('FAILED', err)
// => FAILED [Error: this is an error]
})
// outer is resolved
So, throwing inside either handler will reject the outer promise with the thrown error.
Guideline 2: Anticipate failures in your handlers. Consider whether your rejection handler should be invoked by failures in the resolution handler, or if there should be different behavior.
3. Terminating the promise chain
Guideline 3: Either return your promise to someone else, or if the chain ends with you, call done to terminate it. (from the Q docs)
This has bitten us many times when using promises in Express handlers, and resulted in hard-to-debug hung requests. This handler will never respond to the user:
function handler(req, res, next) {
service.doSomething().then(function onResolve(result) {
throw new Error('this is an error')
res.json({result: 'ok'})
}, function onReject(err) {
res.json({err: err.message}) // Never gets invoked
})
}
Changing the then in the above code to done means that there will be no outer promise returned from this, and the error will result in an asynchronous uncaught exception, which will bring down the Node process. In theory this makes it unlikely that any such problem would make it into production, given how loudly and clearly it would fail during development and testing.
An alternative is to add a final .catch(next) to the promise chain to ensure that any error thrown in either handler will invoke the Express error handler:
function handler(req, res, next) {
service.doSomething().then(function onResolve(result) {
throw new Error('this is an error')
res.json({result: 'ok'})
}, function onReject(err) {
res.json({err: err.message}) // Never gets invoked
})
.catch(next) // next is invoked with the 'this is an error' error
}
This goes against the above guideline, since we are creating a new promise rather than ending the promise chain. You could argue that we trust next not to throw and as such there is no chance for the outer promise to reject, in addition there is no possibility of a hanging request or an uncaught failure (unless you throw undefined in either handler!).
If the idea of done bringing down a Node process makes you uncomfortable enough to ignore this âgolden ruleâ of promise error-handling, then perhaps this is a good option. The important thing is that errors do not hang requests, or get quietly transformed into successes.
Weâve seen 3 simple guidelines which should feel familiar if youâve dealt with synchronous exception handling best practices. In fact they could almost be generalized to apply to both sync and async exception handling:
Throw meaningful errors (and a string is not an error)
Be aware of downstream effects of errors on the flow of execution
Bubble exceptions up to a top level handler
This is a powerful feature of promises - letting us deal with errors in a stye that is more natural to us, as long as we are actually mindful of this, and remember to follow similar rules.
theartofmadeline
jacobvanloon
izzy806
titsay
discoholicmusic
vaporwave