Building robust Node.js applications requires dealing with errors in proper way. This is the third article of a series and aims to give an overview on how to handle errors in async scenarios Node.js.
- Introduction to Errors in Node.js
- Handling errors in synchronous scenarios in Node.js
- Handling errors in asynchronous scenarios in Node.js (this article)
Handling Errors in Asynchronous Scenarios
In the previous article we looked at error handling in sync scenarios, where errors are handled with try/catch
blocks when an error is throw using the throw
keyword. Asynchronous syntax and patterns are focussed on callbacks, Promise abstractions and the async/await
syntax.
There are three ways to handle errors in async scenarios (not mutually inclusive):
- Rejection
- Try/Catch
- Propagation
Rejection
So, when an error occurs in a synchronous function it's an exception, but when an error occurs in a Promise
its an asynchronous error or a promise rejection. Basically, exceptions are synchronous errors and rejections are asynchronous errors.
Let's go back to our divideByTwo()
function and convert it to return a promise:
function divideByTwo(amount) {
return new Promise((resolve, reject) => {
if (typeof amount !== 'number') {
reject(new TypeError('amount must be a number'));
return;
}
if (amount <= 0) {
reject(new RangeError('amount must be greater than zero'));
return;
}
if (amount % 2) {
reject(new OddError('amount'));
return;
}
resolve(amount / 2);
});
}
divideByTwo(3);
The promise is created using the Promise
constructor. The function passed to the Promise
is called tether function , it takes two arguments resolve
and reject
. When the operation is successfully, resolve
is called, and in case of an error reject
is called. The error is passed into reject
for each error case so that the promise will reject on invalid input.
When running the above code the output will be:
(node:44616) UnhandledPromiseRejectionWarning: OddError [ERR_MUST_BE_EVEN]: amount must be even
# ... stack trace
The rejection is unhandled, because a Promise
must use the catch
method to catch rejections. Read more about Promises in the article Understanding Promises in Node.js.
Let's modify the divideByTwo
function to use handlers:
divideByTwo(3)
.then(result => {
console.log('result', result);
})
.catch(err => {
if (err.code === 'ERR_AMOUNT_MUST_BE_NUMBER') {
console.error('wrong type');
} else if (err.code === 'ERRO_AMOUNT_MUST_EXCEED_ZERO') {
console.error('out of range');
} else if (err.code === 'ERR_MUST_BE_EVEN') {
console.error('cannot be odd');
} else {
console.error('Unknown error', err);
}
});
The functionality is now the same as in the synchronous non-promise based code) in the previous article.
When a throw
appears inside a promise handler, it won't be an error, instead it will be a rejection. The then
and catch
handler will return a new promise that rejects as a result of the throw
within the handler.
Async Try/Catch
The async/await
syntax supports try/catch
of rejections, which means that try/catch
can be used on asynchronous promise-based APIs instead of the then
and catch
handlers.
Let's convert the example code to use the try/catch
pattern:
async function run() {
try {
const result = await divideByTwo(1);
console.log('result', result);
} catch (err) {
if (err.code === 'ERR_AMOUNT_MUST_BE_NUMBER') {
console.error('wrong type');
} else if (err.code === 'ERR_AMOUNT_MUST_EXCEED_ZERO') {
console.error('out of range');
} else if (err.code === 'ERR_MUST_BE_EVEN') {
console.error('cannot be odd');
} else {
console.error('Unknown error', err);
}
}
}
run();
The only difference between the synchronous handling is the wrapping in an async function and calling divideByTwo()
with await
, so that the async function can handle the promise automatically.
Using an async
function with try/catch
around an awaited promise is syntactic sugar. The catch
block is basically the same as the catch
handler. An async function always returns a promise that resolves unless a rejection occurs. This also would mean we can convert the divideByTwo
function from returning a promise to simply throw again. Essentially the code is the synchronous version with the async
keyword.
async function divideByTwo(amount) {
if (typeof amount !== 'number')
throw new TypeError('amount must be a number');
if (amount <= 0)
throw new RangeError('amount must be greater than zero');
if (amount % 2) throw new OddError('amount');
return amount / 2;
}
The above code has the same functionality as the synchronous version, but now we can perform other asynchronous tasks, like fetching some data or writing a file.
The errors in all of these examples are developer errors. In an asynchronous context operation errors are more likely to encounter. For example, a POST request fails for some reason, and the data couldn't have been written to the database. The pattern for handling operational errors is the same. We can await
an async operation and catch any errors and handle accordingly (send request again, return error message, do something else, etc.).
Propagation
Another way of handling errors is propagation. Error propagation is where, instead of handling the error where it occurs, the caller is responsible for error handling. When using async/await
functions, and we want to propagate an error we simply rethrow it.
Let's refactor the function to propagate unknown errors:
class OddError extends Error {
constructor(varName = '') {
super(varName + ' must be even');
this.code = 'ERR_MUST_BE_EVEN';
}
get name() {
return 'OddError [' + this.code + ']';
}
}
function codify(err, code) {
err.code = code;
return err;
}
async function divideByTwo(amount) {
if (typeof amount !== 'number')
throw codify(
new TypeError('amount must be a number'),
'ERR_AMOUNT_MUST_BE_NUMBER',
);
if (amount <= 0)
throw codify(
new RangeError('amount must be greater than zero'),
'ERR_AMOUNT_MUST_EXCEED_ZERO',
);
if (amount % 2) throw new OddError('amount');
// uncomment next line to see error propagation
// throw Error('propagate - some other error');;
return amount / 2;
}
async function run() {
try {
const result = await divideByTwo(4);
console.log('result', result);
} catch (err) {
if (err.code === 'ERR_AMOUNT_MUST_BE_NUMBER') {
throw Error('wrong type');
} else if (err.code === 'ERRO_AMOUNT_MUST_EXCEED_ZERO') {
throw Error('out of range');
} else if (err.code === 'ERR_MUST_BE_EVEN') {
throw Error('cannot be odd');
} else {
throw err;
}
}
}
run().catch(err => {
console.error('Error caught', err);
});
Unknown errors are propagated from the divideByTwo()
function, to the catch
block and then up to the run
function with the catch
handler. Try to run the code after uncommenting the throw Error('some other error');
in the divideByTwo()
function to unconditionally throw an error. The output will be something like this: Error caught Error: propagate - some other error
.
If and when an error is propagated depends highly on the context. A reason to propagate an error might be when error handling strategies have failed at a certain level. An example would a failed network request, which was retried for several times before propagating.
In general, try to propagate errors for handling at the highest level possible. This would be the main file in a module, and in an application the entry point file.
TL;DR
- Exceptions are synchronous errors and rejections are asynchronous errors.
- A promise rejection has to be handled. The
catch
handler handles the promise rejection. - There are three ways to handle errors in async scenarios: Rejection, Try/Catch and Propagation
- The
async/await
syntax supportstry/catch
of rejections. -
try/catch
can be used on asynchronous promise-based APIs instead of thethen
andcatch
handlers. - Error propagation is where, instead of handling the error where it occurs, the caller is responsible for error handling.
- Error propagation depends on the context. When propagated it should be to the highest level possible.
Thanks for reading and if you have any questions , use the comment function or send me a message @mariokandut.
If you want to know more about Node, have a look at these Node Tutorials.
References (and Big thanks):
Top comments (0)