Error handling in Node.js

Errors in Node.js are handled through exceptions.

Creating exceptions

An exception is created using the throw keyword:

throw value

As soon as JavaScript executes this line, the normal program flow is halted and the control is held back to the nearest exception handler.

Usually in client-side code value can be any JavaScript value including a string, a number or an object.

In Node.js, we don’t throw strings, we just throw Error objects.

Error objects

An error object is an object that is either an instance of the Error object, or extends the Error class, provided in the Error core module:

throw new Error('Ran out of coffee')

or

class NotEnoughCoffeeError extends Error {
  //...
}
throw new NotEnoughCoffeeError

You can also pass a cause when you wrap an error. That keeps the original error around instead of dropping it:

try {
  //...
} catch (err) {
  throw new Error('Could not brew coffee', { cause: err })
}

The new error keeps the original one in its cause property, so you can add context at a higher layer without losing the root error. If you want to define your own error types, see custom errors in JavaScript.

When several things fail together, for example when Promise.any() rejects, you get an AggregateError instead. Its errors property is an array with every failure inside.

Handling exceptions

An exception handler is a try/catch statement.

Any exception raised in the lines of code included in the try block is handled in the corresponding catch block:

try {
  //lines of code
} catch (e) {

}

e in this example is the exception value.

You can add multiple handlers, that can catch different kinds of errors.

Catching uncaught exceptions

If an uncaught exception gets thrown during the execution of your program, your program will crash.

To solve this, you listen for the uncaughtException event on the process object:

process.on('uncaughtException', (err) => {
    console.error('There was an uncaught error', err)
    process.exit(1) //mandatory (as per the Node docs)
})

You don’t need to import the process core module for this, as it’s automatically injected.

Don’t try to keep running after this handler fires. The Node docs are clear that the process is in an undefined state at that point, so log what you need and exit.

Exceptions with promises

Using promises you can chain different operations, and handle errors at the end:

doSomething1()
  .then(doSomething2())
  .then(doSomething3())
  .catch(err => console.error(err))

How do you know where the error occurred? You don’t really know, but you can handle errors in each of the functions you call (doSomethingX), and inside the error handler throw a new error, that’s going to call the outside catch handler:

const doSomething1 = () => {
  //...
  try {
    //...
  } catch (err) {
    //... handle it locally
    throw new Error('doSomething1 failed', { cause: err })
  }
  //...
}

To be able to handle errors locally without handling them in the function we call, we can break the chain you can create a function in each then() and process the exception:

doSomething1
  .then((() => {
    return doSomething2().catch(err => {
      //handle error
      throw err //break the chain!
    })
  })
  .then((() => {
    return doSomething2().catch(err => {
      //handle error
      throw err //break the chain!
    })
  })
  .catch(err => console.error(err))

Error handling with async/await

Using async/await, you still need to catch errors, and you do it this way:

async function someFunction() {
  try {
    await someOtherFunction()
  }
  catch (err) {
    console.error(err.message)
  }
}

Want me to talk about your product? You can sponsor this site.