DEV Community

loading...
Cover image for Central Error Handling in Express

Central Error Handling in Express

nedsoft profile image Chinedu Orie Updated on ・4 min read

Express is a fast, unopinionated, minimalist web framework for Node.js - docs

Error handling is a routine that one can not do without while building an application either in Express or in any other language.

When building API endpoints using Express or any other framework/library, validation checks are always necessary for each use case, and there's always a need to return an error response to the user. Handling these errors and returning a response for every validation becomes very tedious and makes the codebase messy.
Let's consider an example below:

const validateUser = async (req, res, next) => {
  try {
    const { email, password } = req.body
    if (!email || !password) {
      return res.status(400).json({
        status: 'error',
        message: 'Missing required email and password fields',
      })
    }
    const user = await db.User.findOne({ where: { email }});
    if (!user) {
      return res.status(404).json({
        status: 'error',
        message: 'User with the specified email does not exists',
      })
    }
    next()
  } catch (error) {
    return res.status(500).json({
      status: 'error',
      message: 'An error occurred trying to process your request',
    })
  }
}
Enter fullscreen mode Exit fullscreen mode

Looking at the snippet above, you'd agree with me that it's already looking messy with the returning of error response at every checkpoint. If only that's the code in your codebase, then it wouldn't matter, the matter arises when you have to repeat the same approach across several methods or functions in your codebase.

Before we dive deep to finding a solution to make the snippet above better, let's look at what we need to have for this article:

Requirements

  • NodeJs installed
  • npm or yarn installed
  • Knowledge of Nodejs/Express

Note: This article assumes that the reader already has a basic knowledge of NodeJs/Express. Hence some details may be skipped.

To follow along, clone the repository used for this article here.

Step 1. Create a custom **Error* constructor*
We need to create a custom Error constructor which extends the JavaScript Error constructor.

In the project you cloned earlier, create a directory called helpers. Inside the helpers directory, create a file called error.js

Add the snippet below into the error.js

class ErrorHandler extends Error {
  constructor(statusCode, message) {
    super();
    this.statusCode = statusCode;
    this.message = message;
  }
}
module.exports = {
  ErrorHandler
}
Enter fullscreen mode Exit fullscreen mode

Notice that we exported the ErrorHandler so that we can import it from the index.js file.

Next up, we need to create a function for returning a formatted error response to the user.

Add the snippet below into the error.js file.

const handleError = (err, res) => {
  const { statusCode, message } = err;
  res.status(statusCode).json({
    status: "error",
    statusCode,
    message
  });
};
Enter fullscreen mode Exit fullscreen mode

Update the module.exports block to contain the handleError function as show below:

module.exports = {
  ErrorHandler,
  handleError
}
Enter fullscreen mode Exit fullscreen mode

Step 2. Create the Error-handling middleware

Middleware functions are functions that have access to the request object (req), the response object (res), and the next middleware function in the application’s request-response cycle.
The next middleware function is commonly denoted by a variable named next. Express docs

The error-handling middleware is a special type of middleware that accepts four arguments as opposed to a regular middleware. The first argument is the error object.
The snippet below shows an example of an error-handling middleware:

function(err, req, res, next) {
  //code goes here
}
Enter fullscreen mode Exit fullscreen mode

In the index.js, let's add an error-handling middleware, before then, let's import the handleError function inside the index.js;

The index.js file should look like shown below:

const express = require('express')
const { handleError } = require('./helpers/error')
const app = express()

app.use(express.json())
const PORT = process.env.PORT || 3000

app.get('/', (req, res) => {
  return res.status(200).json('Hello world'); 
})

app.use((err, req, res, next) => {
  handleError(err, res);
});
app.listen(PORT, () => console.log(`server listening at port ${PORT}`))
Enter fullscreen mode Exit fullscreen mode

Notice how we called the handleError function passing the error object and the response object to it.

Note: The error-handling middleware must be the last among other middleware and routes for it to function correctly.

Now anywhere in the application that you want to check for error, all you need to do is to throw the ErrorHandler constructor.
We can now apply the error-handling mechanism to refactor the messy code we had earlier. It should look like shown below:

const validateUser = async (req, res, next) => {
  try {
    const { email, password } = req.body
    if (!email || !password) {
      throw new ErrorHandler(404, 'Missing required email and password fields')
    }
    const user = await  db.User.findOne({ where: { email }});
    if (!user) {
      throw new ErrorHandler(404, 'User with the specified email does not exists')
    }
    next()
  } catch (error) {
    next(error)
  }
}
Enter fullscreen mode Exit fullscreen mode

Notice how we passed the error to the next function above. What that simply does is to pass the error to the error-handling middleware we defined in index.js.

Let's add a route to test our error-handling mechanism that we just created. In the index.js add the snippet below:

app.get('/error', (req, res) => {
  throw new ErrorHandler(500, 'Internal server error');
})
Enter fullscreen mode Exit fullscreen mode

Remember to import the ErrorHandler in index.js. It should look like shown below:

const { handleError, ErrorHandler } = require('./helpers/error')
Enter fullscreen mode Exit fullscreen mode

Start the server by running, npm start and then visit the route /error. You'd get a response similar to the one shown below:

{
    "status": "error",
    "statusCode": 500,
    "message": "Internal server error"
}
Enter fullscreen mode Exit fullscreen mode

Conclusion

In this article, we've established the need to have a central error handler in our Express application. We also demonstrated the steps that we need to take to implement a central error handler.

If you have any question or contributions to make this article better, kindly reach out to me via Twitter.
Thanks for reading through. ✌️

Discussion (40)

pic
Editor guide
Collapse
jakub41 profile image
Jakub

Hello,
I really like this post as I'm learning a better way of handling errors.

I have a question about when you add in the .catch(err) { next(err) }
Is this actually throwing out an error from server or I should still use like you did before
throw new ErrorHandler(500, 'Internal server error');

Or that next(err)is doing it?

I just not get that and I would like to understand it.

I have an example of how I used:

async getAll(req, res, next) {
        try {
            const profiles = await db.Profile.find({});
            if (!profiles)
                throw new ErrorHandler(404, "No profiles are found!");

            res.send({
                profiles
            });

            next();
        } catch (err) {
            next(err);
        }
    },

Thanks for help :)
Collapse
trannguyen61 profile image
trannguyen61

Since getAll is a middleware, it must call next() to tell the server to continue processing the next step after that, or else it will be blocked and never return any responses to the client. The error thrown in try block is then caught in catch block, through the name of err.
Therefore, calling next(err) means passing err to the next error-handling middleware while keeping the flow of your app running.

Collapse
briantuju profile image
Brian

The best error handling mechanism I've seen so far. I have a question though.

I understand that i have to require this in the index file:

const { handleError } = require("path-to-code")

Will I have to include this code

const { ErrorHandler } = require("path-to-code");

in every file where I need to handle errors apart from the index file?

Collapse
nedsoft profile image
Chinedu Orie Author

It's like any other module, you will have to require/import it anywhere you need to use it. No specific exceptions, it depends on the use case.

Collapse
briantuju profile image
Brian

Thank you so much

Collapse
maxiqboy profile image
Thinh Nguyen

Great Article, Thanks

btw, I got a small question in this own Error class :

class ErrorHandler extends Error {
  constructor(statusCode, message) {
    super();
    this.statusCode = statusCode;
    this.message = message;
  }
}
module.exports = {
  ErrorHandler
}

Why we have to write like this (1)

super();
this.message = message;

but not like this (2)

super(message);

?

Actually, I wrote like (2) and then my own class lost a message property

It only comes back when I change it to (1).

What is the difference between them ?

Thanks,

Collapse
nedsoft profile image
Chinedu Orie Author

The super() method is used when a class (child) inherits from another class (parent).
The super() method provides a means of syncing the child's constructor to the parent's constructor.
Let me illustrate with an example

class Foor {
    constructor(name) {
        this.name = name
   }
    printName = () => {
      console.log(this.name);
   }
}

class Bar extends Foo {

     constructor(name) {
         super(name)
   }
}

const bar = new Bar('Test');

bar.printName() // Test



Now, looking at the code above,
Foorequires anameto be passed to its constructor in order to function, whenBarinherited fromFoo, there's no way thenamecould be passed down toFooif not with thesuper()`

So, in relation to the snippet that you shared above, you are passing the message to the parent which in this case is Error, that way the child ErrorHandler has no access to message

I hope this helps.

Collapse
peacefulseeker profile image
Alexey Vorobyov

Is there a necessity in Bar constructor at all?
You just pass the same Test value to the parent class ultimately. In this case
there is no need to a constructor at all I assume and Eslint should also hint about it.

Collapse
rodrigoabb profile image
Rodrigo Abbás

Hi Chinedu,

Thank you very much for your post! This is what I've been wanting to implement, but somehow I couldn't figure out a simple way.
I adapted it a little bit to my code but applied the same principle you are describing.
Again, thanks man!
Cheers!

Collapse
ajaysainy profile image
Ajay Sainy

Thanks for a useful post. One question on usage of validateUser method. How do we use that method in lets say any PUT path that validates a user?
Simply calling validateUser(req, res, next) is causing the error Error [ERR_HTTP_HEADERS_SENT]: Cannot set headers after they are sent to the client in the code below validateUser call that assumes the user is already validated.

I am guessing this is happening because express does not immediate terminates the request processing after the response has been sent to the client.

Collapse
nedsoft profile image
Chinedu Orie Author

I think your guess is right. Sometimes it happens if a return statement is skipped somewhere, so the execution continues after the first error encounter

Collapse
mr_cea profile image
Ogbonna Basil

This is cool,

Just one opinion, i feel it should be expanded to be not just Error Handler but statusHandler

```
class statusHandler extends Error {
constructor(statusCode, message, data) {
super();
this.statusCode = statusCode;
this.message = message;
this.data = data || null

}
}
module.exports = {
statusHandler
}




Likewise for handleError but generally this approach is effectively DRY. Nice one
Collapse
nedsoft profile image
Chinedu Orie Author

Just like Express is unopinionated, how you apply the concept in the article is also unopinionated. And except I do not understand you clearly, it'd not make sense semantically to throw a success response as an error. Thanks for sharing your views.

Collapse
oim5nu profile image
Yuanpeng Zheng

Great post. Buddy. Just got one question here.

const validateUser = async (req, res, next) => {
  try {
    .....
    next()
  } catch (error) {
    next(error)
  }

  res.on('finish', () => {
     // How could you handle the error here for express? Thanks. 
  }
}
Collapse
kopax profile image
Dimitri KOPRIWA

Hi and thanks for this article, I have tried to implement it and instead of having the errorMiddleware called when I throw new ErrorHandler(500) within my route, I have in the console: (node:16482) UnhandledPromiseRejectionWarning: Error: Server Error what part did I miss? thanks

Collapse
leivermoreno profile image
Leiver Moreno

Just what I was looking for, I'm learning Express.
Just one doubt, what in case of, for example, a database error? Which is no enclosed by an if statement and there is no error throw for it. Therefore the express error middleware is called and ErrorHandler object is instantiated with code and message set to undefined.

The solution I propose is to add an if statement in the ErrorHandler constructor to check if the given values are undefined. Let know your opinion and if I'm wrong.

Collapse
algol007 profile image
Ady Rahmansyah

Thank you. It's really helpful

Collapse
omancoding profile image
OmanCoding

Thank you for the article, I learned something.

I have question, how does Express know that next(error), should be passed to the Error Handling middleware (which has 4 arguments)?

If there is a middleware that has (res, req, next) that was sat up before the Error Handling middleware, will it get first to handle the error?

Nasser

Collapse
leivermoreno profile image
Leiver Moreno

This happens because even if you do not configure a middleware for error handling, express does it internally for you, so when an error occurs, all subsequent middlewares are skipped until the error handling middleware. How does express know what this middleware is? Because it has four arguments, error, req, res, next.

Collapse
rajeshbarik66 profile image
Rajesh Barik

Hi, This is an awesome article. I just have one problem. I implemented it, but whenever I use this throw error, my server crashes with error throw er; // Unhandled 'error' event. What did I do wrong ? Could you please help me ?

Collapse
taniarascia profile image
Tania Rascia

This is great, thank you! Exactly what I needed.

Collapse
nedsoft profile image
Chinedu Orie Author

Glad to learn you found it helpful. ✌️

Collapse
klevamane profile image
Richard Onengiye

Awesome Awesome stuff....

Collapse
nedsoft profile image
Collapse
ogwurujohnson profile image
Johnson Ogwuru

This is some good stuff, mate

Collapse
nedsoft profile image
Collapse
areljannc profile image
AJ Clemente

This is it, chief. This is exactly what I'm looking.

I've been trying to figure out to make our back-end code cleaner and I think this post has answered all of my questions.

Thank you and take care!

Collapse
nedsoft profile image
Chinedu Orie Author

Glad to hear that you found it helpful

Collapse
rejaulkarim profile image
Rejaul Karim 🔥

what about global error? you code din't handle global error?

Collapse
chan_austria777 profile image
chan 🤖

exactly what i was thinking. I feel like all uncaught exceptions won't be created as a custom Error

Collapse
jorgee97 profile image
Jorge Gomez

Thanks for the article Orie, it really help me a lot.

Collapse
hirengohil13 profile image
Hiren Gohil

Nice Article

Can we make common structure for Error & Success both ?

Collapse
manoellribeiro profile image
Manoel Ribeiro

It's a really nice content, thank you for the help!!

Collapse
minemaxua profile image
Maksym Minenko

Maybe super(message) instead of just super()?

Collapse
hirengohil13 profile image
Hiren Gohil

ReferenceError: ErrorHandler is not defined

const { handleError, ErrorHandler } = require('./helpers/error')
Imported ErrorHandler but not used into Index file.

Collapse
iamdjarc profile image
IG:DjArc [Hey-R-C]

Hey Chinedu, thank you for this article. I have a question on Testing.

How do you actually test the: "next(error)" I am using nest and I am having a hard time capturing that.

Thank you.

Collapse
javabytes profile image
JavaBytes

Thank you so much for this article! it was very clear and well explained each step of the way. Very helpful!

Collapse
yuriytigiev profile image
YuriyTigiev

Why for a success case the last step is next(), but not a return res.status(200)?

Collapse
nedsoft profile image
Chinedu Orie Author

It's because, the function is a middleware, not a final destination, with next() returned, it would proceed to the next code to be executed.

Collapse
muhammadahmed8 profile image
Muhammad Ahmed

Hello, nice post. If I use express-validation, how could I throw my custom error class from express-validation? Thank you.