Express Error-Handling Middleware Explained

Express Error-Handling Middleware Explained

Error handling in Express has a special middleware shape. Here is how to use it.

The Shape

An error-handling middleware has four parameters (Express uses arity to detect it):

app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(err.status || 500).json({
    error: err.message || 'Something went wrong'
  });
});

Register it last, after all routes. Express jumps to it when a middleware or handler calls next(err) or throws.

Throwing Errors in Handlers

router.get('/users/:id', async (req, res, next) => {
  const user = await User.findById(req.params.id);
  if (!user) return next(new Error('User not found'));
  res.json(user);
});

Or throw (with async wrapper or Express 5):

if (!user) throw new ApiError(404, 'User not found');

Custom ApiError Class

class ApiError extends Error {
  constructor(status, message) {
    super(message);
    this.status = status;
  }
}

Now you can throw new ApiError(404, 'User not found') and the error handler reads err.status and err.message.

Catching Async Errors

Express 4 does not catch promise rejections. Use a wrapper:

const asyncHandler = fn => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

router.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) throw new ApiError(404, 'User not found');
  res.json(user);
}));

Express 5 catches async errors automatically.

Don't Leak Stack Traces

In production, do not send the stack:

res.status(err.status || 500).json({
  error: process.env.NODE_ENV === 'production'
    ? (err.expose ? err.message : 'Something went wrong')
    : err.message,
  stack: process.env.NODE_ENV === 'production' ? undefined : err.stack
});

Use an expose flag on ApiError for errors that are safe to show (validation, not found). For 500s, send a generic message.

Logging

Log errors with a real logger (winston, pino), not console.error:

app.use((err, req, res, next) => {
  logger.error({ err, path: req.path, method: req.method, userId: req.user?.id });
  res.status(err.status || 500).json({ error: err.message });
});

For real apps, integrate Sentry or similar for error alerts.

Multiple Error Handlers

You can have multiple error-handling middlewares, e.g., one for known ApiErrors and one for unknown errors:

app.use((err, req, res, next) => {
  if (err instanceof ApiError) return res.status(err.status).json({ error: err.message });
  next(err);
});
app.use((err, req, res, next) => {
  logger.error({ err });
  res.status(500).json({ error: 'Something went wrong' });
});

The Takeaway

Express error handling uses a four-parameter middleware. Throw or call next(err) in handlers. Use a custom ApiError class with status and message. Wrap async handlers to catch promise rejections. Never leak stack traces in production. Log with a real logger and integrate Sentry. Register error handlers last.