🛡️ Error Handling Middleware

Why Centralize Error Handling?

Imagine a busy restaurant kitchen. Instead of every cook stopping to personally apologize to a diner when a dish burns, there's one expediter at the pass who intercepts every problem plate, decides what the customer sees, and keeps the line moving. Centralized error handling is that expediter for your API: routes don't each craft their own error responses — they just hand the problem off, and one place decides how to respond.

Without it, error handling gets copy-pasted into every route: the same res.status(500).json(...), the same logging, the same "did I remember to handle this?" anxiety. Miss one, and an unhandled error can crash the whole Node process. Centralizing gives you consistency (every error looks the same to clients), safety (nothing slips through), and maintainability (change the format once).

Notice how every path — thrown errors, forwarded errors, even requests that match no route — funnels into a single middleware. That funnel is what the rest of this lesson builds.

The Four-Argument Handler

Regular Express middleware takes three parameters: (req, res, next). Error-handling middleware takes four: (err, req, res, next). That extra leading err parameter is not just convention — it is how Express identifies the function as an error handler. Express inspects the function's arity (its number of declared parameters), and a middleware declared with exactly four arguments is routed to only when an error is in flight.

const express = require('express');
const app = express();

app.get('/api/items', (req, res) => {
  res.json([{ id: 1, name: 'Widget' }]);
});

// Error-handling middleware — note the FOUR parameters.
// It runs only when something upstream passed an error along.
app.use((err, req, res, next) => {
  console.error(err.stack);            // log for the developer
  const status = err.statusCode || 500;
  res.status(status).json({
    error: { message: err.message || 'Something went wrong' }
  });
});

app.listen(3000, () => console.log('Server running on port 3000'));

One more rule: register your error handler last, after all your routes and other middleware. Express walks its middleware stack top to bottom, and an error handler can only catch errors from middleware defined before it.

How Errors Reach the Handler

For synchronous code, Express does the work for you. If you throw inside a route handler, Express catches it and forwards it to your error middleware automatically — no wiring required.

app.get('/api/items/:id', (req, res) => {
  const { id } = req.params;
  if (!/^\d+$/.test(id)) {
    // A synchronous throw — Express catches this and routes it
    // to the error-handling middleware for you.
    const err = new Error('Item id must be numeric');
    err.statusCode = 400;
    throw err;
  }
  res.json({ id: Number(id) });
});

You can also forward an error manually by calling next(err) — passing any argument to next() tells Express "skip the remaining normal middleware and jump to the error handler." Calling next() with no argument means "continue normally." This distinction is the heart of Express error flow.

Async Errors & next(err)

Here is the trap that catches almost everyone: Express's automatic catching works for synchronous throws only. If you throw inside an async function (or a rejected promise settles), Express 4 does not see it — the request hangs and Node logs an unhandled rejection. Async errors must be forwarded deliberately.

Option 1 — try/catch with next(err)

app.get('/api/users/:id', async (req, res, next) => {
  try {
    const user = await User.findById(req.params.id);
    if (!user) {
      const err = new Error('User not found');
      err.statusCode = 404;
      throw err;                 // caught locally by the catch below
    }
    res.json(user);
  } catch (err) {
    next(err);                   // hand off to the central error handler
  }
});

This works, but wrapping every async route in try/catch gets repetitive fast.

Option 2 — an asyncHandler wrapper

A tiny higher-order function removes the boilerplate. It runs your handler, and if the returned promise rejects, it pipes the error into next for you.

// A reusable wrapper: resolve the handler's promise, and
// on rejection, forward the error to Express automatically.
const asyncHandler = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

// No try/catch needed — a thrown error is forwarded for you.
app.get('/api/users/:id', asyncHandler(async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) {
    const err = new Error('User not found');
    err.statusCode = 404;
    throw err;
  }
  res.json(user);
}));

Operational vs Programmer Errors

Not all errors are equal. A professional error strategy splits them into two buckets, and the split drives how you respond.

The common convention is an isOperational flag on the error. Errors you throw on purpose (a 404, a 400) are marked operational; anything else — an unexpected TypeError — is treated as a programmer error whose details you must not reveal to clients.

// Deliberately thrown = operational. We trust its message.
const err = new Error('Email is already registered');
err.statusCode = 409;
err.isOperational = true;
throw err;

// An accidental bug is NOT operational:
const data = undefined;
data.items.forEach(/* ... */);   // TypeError — a programmer error

In the next lesson you'll formalize this with custom Error subclasses that set statusCode and isOperational automatically, so throwing the right error becomes a one-liner.

A Complete Error Pipeline

Let's assemble the pieces into a realistic setup. Three parts, in order: a 404 handler for unmatched routes, then the final error handler, both registered after your routes.

// app.js
const express = require('express');
const app = express();

app.use(express.json());

// --- Your routes ---
app.use('/api/users', require('./routes/users'));
app.use('/api/items', require('./routes/items'));

// 1) 404 handler — reached only if no route above matched.
//    Build an error and forward it; don't respond here.
app.use((req, res, next) => {
  const err = new Error(`Not found: ${req.method} ${req.originalUrl}`);
  err.statusCode = 404;
  err.isOperational = true;
  next(err);
});

// 2) Centralized error handler — the single source of truth
//    for what an error response looks like.
app.use((err, req, res, next) => {
  const status = err.statusCode || 500;
  const isDev = process.env.NODE_ENV !== 'production';

  // Log every error server-side with useful context.
  console.error(`[${new Date().toISOString()}] ${req.method} ${req.originalUrl}`, err);

  res.status(status).json({
    error: {
      message: err.isOperational ? err.message : 'Internal server error',
      ...(isDev && { stack: err.stack })   // stack only in development
    }
  });
});

module.exports = app;

Production Safety

A stack trace is a gift to a developer and a gift to an attacker. It can reveal file paths, library versions, query structure, even snippets of internal logic. The golden rule: never send stack traces or raw error details to clients in production.

app.use((err, req, res, next) => {
  const status = err.statusCode || 500;
  const isProd = process.env.NODE_ENV === 'production';

  // Operational errors carry a safe, client-friendly message.
  // Everything else is masked behind a generic message in prod.
  const message = (err.isOperational || !isProd)
    ? err.message
    : 'Something went wrong. Please try again later.';

  const body = { error: { message } };
  if (!isProd) body.error.stack = err.stack;   // dev convenience only

  res.status(status).json(body);
});

// development
{ "error": { "message": "Cannot read properties of undefined",
             "stack": "TypeError: ... at /app/routes/users.js:14" } }

// production
{ "error": { "message": "Something went wrong. Please try again later." } }

Two more production essentials: guard the process against truly unexpected failures, and always log before you mask.

// Last-resort safety nets at the process level.
process.on('unhandledRejection', (reason) => {
  console.error('Unhandled Rejection:', reason);
  // Log/alert, then let a supervisor (pm2, Docker, systemd) restart.
});

process.on('uncaughtException', (error) => {
  console.error('Uncaught Exception:', error);
  process.exit(1);   // a programmer error left the app in an unknown state
});

Practice & Quiz

const express = require('express');
const app = express();
app.use(express.json());

const items = [{ id: 1, name: 'Widget' }];

app.get('/api/items/:id', /* wrap me */ async (req, res) => {
  const item = items.find(i => i.id === Number(req.params.id));
  if (!item) { /* throw a 404 */ }
  res.json(item);
});

// TODO: 404 handler
// TODO: error handler
app.listen(3000);

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

app.get('/api/items/:id', asyncHandler(async (req, res) => {
  const item = items.find(i => i.id === Number(req.params.id));
  if (!item) {
    const err = new Error('Item not found');
    err.statusCode = 404;
    err.isOperational = true;
    throw err;
  }
  res.json(item);
}));

// 404 for unmatched routes
app.use((req, res, next) => {
  const err = new Error(`Not found: ${req.originalUrl}`);
  err.statusCode = 404;
  err.isOperational = true;
  next(err);
});

// centralized error handler (must be LAST, four args)
app.use((err, req, res, next) => {
  const status = err.statusCode || 500;
  const isProd = process.env.NODE_ENV === 'production';
  console.error(err);
  res.status(status).json({
    error: {
      message: (err.isOperational || !isProd)
        ? err.message : 'Internal server error',
      ...(!isProd && { stack: err.stack })
    }
  });
});

app.use((err, req, res) => {
  res.status(500).json({ error: err.message });
});

Best Practices & Pitfalls

✅ Do

• Keep one centralized error handler and register it last
• Forward every error with next(err) — let routes stay focused on the happy path
• Wrap async handlers (or use Express 5) so rejected promises reach the handler
• Attach a statusCode and isOperational flag to errors you throw on purpose
• Log the full error server-side, always, before deciding what to send

❌ Don't

• Write res.status(500).json(...) in every route — that's what you're centralizing away
• Send err.stack or raw DB messages to clients in production
• Forget the fourth parameter on the handler (a silent, maddening bug)
• Call next(err) after you've already sent a response — you'll get "headers already sent"
• Swallow errors with an empty catch {} — a hidden failure is worse than a loud one

Summary

📚 Additional Resources

• Express — Error handling guide
• Express — Migrating to Express 5 (async error forwarding)
• Node.js — Errors documentation
• MDN — Error object

🚀 What's Next?

Right now most errors we throw are for bad input — and hand-checking every field is tedious and error-prone. The next lesson introduces a library that does it declaratively: Input Validation with Express-validator, where you'll build validate → sanitize → handle pipelines that catch bad data before it ever reaches your logic.