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

Handling Errors in Node.js (synchronous)

Creating, managing and propagating errors in sync 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 second article of a series and aims to give an overview on how to handle errors in Node.js.

Handling Operation Errors

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

Error handling can't be centralized in one part of the application, just like performance and security. When writing code a scenario (what might fail and what are the implications on the application) for an error has to be considered. It does not mean that the code will fail, but if could, it will sooner or later. The appropriate handling of errors depend on exactly what failed and why.

There are a few things that can be done when an error occurs:

  • Deal with error directly. When it's clear how to handle an error, just do it directly.
  • Propagate the error to your client. If you don’t know how to deal with the error, a simple solution would be to stop the operation, clean up whatever has started, and deliver the error back to the client.
  • Retry the operation. It's useful to retry the operation with network errors and errors in remote services.
  • Blow up. If there is an error, that is extraordinary it might be ok to log an error message and crash.
  • Log the error and do nothing else. Sometimes there is nothing you can do (retry or abort), and the application can still work, there is no reason to crash. Just log the error.

Handling Developer Errors

There’s nothing you can do to handle a programmer error. The code who should do something is broken, you can't fix broken code with more code. For example in a REST server a request handler throws ReferenceError, because there is a mistyped variable name.

The best way to handle developer errors is to crash immediately and restart automatically in an event of crash. The downside on this is that connect clients will be temporarily disrupted.

Handling Errors in Synchronous Functions

When an error is thrown in a synchronous function it can be handled with a try/catch block.

Lets refactor the example from the previous article to use try/catch:

class OddError extends Error {
  constructor(varName = '') {
    super(varName + ' must be even');
  }
  get name() {
    return 'OddError';
  }
}

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;
}

try {
  const result = divideByTwo(3);
  console.log('result', result);
} catch (err) {
  console.error('Error caught: ', err);
}

The output will be:

# ... file path

Error caught: OddError [ERR_MUST_BE_EVEN]: amount must be even.

# ... stack trace

With the try/catch pattern we were able to control the error output to the terminal. When the input to the function divideByTwo() is invalid an error will be thrown, and the execution doesn't proceed to the next line and instead jumps to the catch block. But rather than logging an error, we can check what type of error has occurred and handle it accordingly:

class OddError extends Error {
  constructor(varName = '') {
    super(varName + ' must be even');
  }
  get name() {
    return 'OddError';
  }
}

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;
}

try {
  const result = divideByTwo(3);
  console.log('result', result);
} catch (err) {
  if (err instanceof TypeError) {
    console.error('wrong input type');
  } else if (err instanceof RangeError) {
    console.error('out of range');
  } else if (err instanceof OddError) {
    console.error('cannot be odd');
  } else {
    console.error('Unknown error', err);
  }
}

Checking for the instance of error is flawed, consider the following change code:

try {
  const result = divideByTwo(4);
  result();
  console.log('result', result);
} catch (err) {
  if (err instanceof TypeError) {
    console.error('wrong input type');
  } else if (err instanceof RangeError) {
    console.error('out of range');
  } else if (err instanceof OddError) {
    console.error('cannot be odd');
  } else {
    console.error('Unknown error', err);
  }
}

We are calling result(), which is an error, since result is value returned from divideByTwo(4), which should be 2. The output will be wrong type. This can lead to confusion, since the checking of errors was written to handle errors in divideByTwo(), and not from any other function in the try block.

To mitigate this it is recommended to use duck-taping. This means looking for certain qualities to determine what an object is. If it looks like a duck and sounds like a duck, it must be a duck.

Let's write a small utility function to add code to an error object:

function addCodeProperty(err, code) {
  err.code = code;
  return err;
}

Now we update the divideByTwo() function and the try/catch block with the updated if-statement for err.code.

function divideByTwo(amount) {
  if (typeof amount !== 'number')
    throw addCodeProperty(
      new TypeError('amount must be a number'),
      'ERR_AMOUNT_MUST_BE_A_NUMBER',
    );
  if (amount <= 0)
    throw addCodeProperty(
      new RangeError('amount must be greater than zero'),
      'ERR_AMOUNT_MUST_EXCEED_ZERO',
    );
  if (amount % 2) throw new OddError('amount');
  return amount / 2;
}

try {
  const result = divideByTwo(4);
  result();
  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);
  }
}

Now the error from result() is handled properly. The output will be:

# ... file path

Unknown error TypeError: result is not a function

# ... stack trace

IMPORTANT: Try/Catch cannot catch errors that are thrown in a callback function that is called later.

TL;DR

  • When an error is thrown in a synchronous function it can be handled with a try/catch block.
  • Try/Catch cannot catch errors that are thrown in a callback function that is called later (i.e. with setTimeout())
  • Differentiating by instanceof is flawed, a code property should be added to the error to differentiate (see example above).

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 ↑