Handling Errors in Node (asynchronous)
© https://nodejs.org/en/

Handling Errors in Node (asynchronous)

Creating, managing and propagating errors in async scenarios.

ByMario Kandut

honey pot logo

Europe’s developer-focused job platform

Let companies apply to you

Developer-focused, salary and tech stack upfront.

Just one profile, no job applications!

This article is based on Node v16.14.0.

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.

Handling Errors in Asynchronous Scenarios

💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

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 supports try/catch of rejections.
  • try/catch can be used on asynchronous promise-based APIs instead of the then and catch 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):

JSNAD, MDN Errors, MDN throw, Node.js Error Codes, Joyent

More node articles:

Getting started with Webpack

How to list/debug npm packages?

How to specify a Node.js version

How to create a web server in Node.js

How to dynamically load ESM in CJS

How to convert a CJS module to an ESM

How to create a CJS module

How to stream to an HTTP response

How to handle binary data in Node.js?

How to use streams to ETL data?

How to connect streams with pipeline?

How to handle stream errors?

How to connect streams with pipe?

What Is a Node.js Stream?

Handling Errors in Node (asynchronous)

Handling Errors in Node.js (synchronous)

Introduction to errors in Node.js

Callback to promise-based functions

ETL: Load Data to Destination with Node.js

ETL: Transform Data with Node.js

ETL: Extract Data with Node.js

Event Emitters in Node.js

How to set up SSL locally with Node.js?

How to use async/await in Node.js

What is an API proxy?

How to make an API request in Node.js?

How does the Event Loop work in Node.js

How to wait for multiple Promises?

How to organize Node.js code

Understanding Promises in Node.js

How does the Node.js module system work?

Set up and test a .env file in Node

How to Use Environment Variables in Node

How to clean up node modules?

Restart a Node.js app automatically

How to update a Node dependency - NPM?

What are NPM scripts?

How to uninstall npm packages?

How to install npm packages?

How to create a package.json file?

What Is the Node.js ETL Pipeline?

What is data brokering in Node.js?

How to read and write JSON Files with Node.js?

What is package-lock.json?

How to install Node.js locally with nvm?

How to update Node.js?

How to check unused npm packages?

What is the Node.js fs module?

What is Semantic versioning?

The Basics of Package.json explained

How to patch an NPM dependency

What is NPM audit?

Beginner`s guide to NPM

Getting started with Node.js

Scroll to top ↑