Introduction to errors in Node.js

Introduction to errors in Node.js

Creating, managing and propagating errors in sync and async scenarios.

By Mario Kandut

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. Error handling in Node.js is an opinionated topic. This is the first article of a series. It aims to give an overview of different kind of errors in Node.js and the creation and throwing of errors.

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

Handling Errors in Node.js:

What kinds of errors exist in Node.js?

There are basically two groups:

  • Operational Errors
  • Developer Errors

Operational Errors are errors that happen while a program is working on a task, like a network failure. Handling of operational errors should be covered by applying an appropriate scenario strategy. In case of a network error, a strategy would be to retry the network operation.

Operation errors are:

  • failed to connect to server
  • failed to resolve hostname
  • invalid user input
  • request timeout
  • server returned a 500 response
  • system is out of memory
  • etc.

Developer Errors are mistakes of developers, for example invalid input. In these cases the application should not attempt to continue running and should crash with a helpful description so that the developer can fix this issue.

Developer Errors are:

  • tried to read property of undefined
  • called an asynchronous function without a callback
  • passed a string where an object was expected
  • passed an object where a property is missing but required
  • etc.

Throwing Errors

Typically, an error is dealt with by using the throw keyword to throw an exception. The throw statement throws a user-defined exception and execution of the current function will stop. Statements after throw won't be executed, and the first catch block will receive the error. If no catch block exists in the function context, the program will terminate.

For example:

function divideByTwo(amount) {
  if (typeof amount !== 'number')
    throw new Error('amount must be a number');
  return amount / 2;

When divideByTwo is called with an invalid input, a string instead of number, the application will crash, and the stack trace is printed in the console. This stack trace comes from the error object which was created after using the throw keyword. The Error constructor is native to JavaScript, takes a string as the Error message and auto-generates the stack trace when created.

It is recommended to throw an Error Object, but theoretically any value can be thrown. The stack trace will be lost in that case.

function divideByTwo(amount) {
  if (typeof amount !== 'number') throw 'amount must be a number'; // NOT RECOMMENDED
  return amount / 2;

Native Error Constructors

To create an error, call new Error('message') and pass a string value as a message.

new Error('this is a error message');

There are six other native error constructors that inherit from the base Error constructor in JavaScript:

  • EvalError
  • SyntaxError
  • RangeError
  • ReferenceError
  • TypeError
  • URIError

A ReferenceError will be automatically thrown, when attempting to refer to a non-existing reference. This node -p 'thisReference' will throw a ReferenceError since the reference does not exist.

An error object can also have its instance verified, like node -p "const err = new SyntaxError(); err instanceof SyntaxError will return true. This node -p "const err = new SyntaxError(); err instanceof Error will also be valid, since any native error constructor inherits from Error.

Native errors objects also have a name property, which contains the name of the error that created it. node -p "const err = new RangeError(); console.log('error is: ',;"

Custom Errors

The native errors are a rudimentary set of errors that can't replicate all errors that can occur in an application. For that we have custom errors. There are several ways of communicating various errors, the most common two are subclassing native error constructors and using the code property.

Let's look at an example to see how a custom error with the code property looks like:

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) {
    const err = Error('amount must be even');
    err.code = 'ERR_MUST_BE_EVEN';
    throw err;
  return amount / 2;

Now run the function with divideByTwo(3) in the REPL or create a file and execute the function add the end. The outcome will be something like this:

# ... filepath

throw err;

Error: amount must be even
# ... stack trace

The error can be identified by the code value that was added and then handled accordingly. The code API in Node.js uses a similar approach to create native errors. For a list of possible error codes see in the official docs - Node.js v16.5 - List of Error Codes.

Another way to create custom errors is to inherit ourselves from the Error object and create a custom error instance. Let's create an OddError constructor:

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

Now we'll update the divideByTwo() to use OddError. The custom error has to be in the same file or imported:

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 output will be:

# ... file path
    if (amount % 2) throw new OddError('amount');

OddError: amount must be even
# ... stack trace

The strategy to use a custom error constructor and adding a code property are not mutually exclusive, so both can be used at the same time. Let's update the OddError example:

class OddError extends Error {
  constructor(varName = '') {
    super(varName + ' must be even');
    this.code = 'ERR_MUST_BE_EVEN';
  get name() {
    return `OddError [${this.code}]`;

The output after execution will be:

# ... file path
if (amount % 2) throw new OddError('amount');
OddError [ERR_MUST_BE_EVEN]: amount must be even
# ... stack trace


  • Errors in Node.js are handled through exceptions.
  • An error can be created with using the constructor new Error('error message') and thrown using the throw keyword.
  • Always throw Error object instead of value to keep stack trace.
  • There are six native error constructors which inherit from Error.
  • Custom errors can be created with the code property and/or using a constructor with inheriting from the Error object.

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:

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 ↑