Handling 404 and Error Routes in Express

Two things are certain in every Express API: some requests will arrive for routes that do not exist, and some requests that do match a route will trigger errors — database failures, validation problems, invalid IDs, or unexpected exceptions. Handling both cleanly — with consistent JSON responses, correct HTTP status codes, and no unhandled promise rejections crashing your server — is what distinguishes a production-ready API from a prototype. In this lesson you will build a complete Express error handling layer covering 404 catch-all handlers, global error middleware, custom error classes, and the async wrapper pattern.

Express Error Handling — The Four Rules #

The 404 Not Found Handler #

// server/src/middleware/notFound.js
const notFound = (req, res, next) => {
  const error = new Error(`Route not found: ${req.method} ${req.originalUrl}`);
  error.statusCode = 404;
  next(error); // pass to the global error handler
};

module.exports = notFound;

// In index.js — registered AFTER all routes:
app.use('/api/posts', require('./src/routes/posts'));
app.use('/api/auth',  require('./src/routes/auth'));

app.use(notFound);       // 404 catch-all ← after all routes
app.use(errorHandler);   // global error handler ← very last

Global Error Middleware #

// server/src/middleware/errorHandler.js
const errorHandler = (err, req, res, next) => {
  // Log the full error server-side (never expose stack traces to clients)
  console.error(`[ERROR] ${err.name}: ${err.message}`);
  if (process.env.NODE_ENV === 'development') {
    console.error(err.stack);
  }

  // Default status code and message
  let statusCode = err.statusCode || err.status || 500;
  let message    = err.message    || 'Internal Server Error';

  // ── Handle specific Mongoose / MongoDB error types ──────────────────────────

  // CastError: invalid MongoDB ObjectId format
  if (err.name === 'CastError' && err.kind === 'ObjectId') {
    statusCode = 400;
    message    = `Invalid ID format: ${err.value}`;
  }

  // ValidationError: Mongoose schema validation failed
  if (err.name === 'ValidationError') {
    statusCode = 400;
    message    = Object.values(err.errors).map(e => e.message).join(', ');
  }

  // MongoServerError code 11000: duplicate key (e.g. email already exists)
  if (err.code === 11000) {
    const field = Object.keys(err.keyValue)[0];
    statusCode  = 409;
    message     = `${field} already exists`;
  }

  // JsonWebTokenError: invalid JWT
  if (err.name === 'JsonWebTokenError') {
    statusCode = 401;
    message    = 'Invalid token';
  }

  // TokenExpiredError: expired JWT
  if (err.name === 'TokenExpiredError') {
    statusCode = 401;
    message    = 'Token expired — please log in again';
  }

  res.status(statusCode).json({
    success: false,
    message,
    // Only include stack trace in development
    ...(process.env.NODE_ENV === 'development' && { stack: err.stack }),
  });
};

module.exports = errorHandler;

Custom AppError Class #

// server/src/utils/AppError.js
class AppError extends Error {
  constructor(message, statusCode) {
    super(message);
    this.statusCode  = statusCode;
    this.status      = `${statusCode}`.startsWith('4') ? 'fail' : 'error';
    this.isOperational = true; // distinguishes known errors from unexpected bugs
    Error.captureStackTrace(this, this.constructor);
  }
}

module.exports = AppError;

// Usage anywhere in controllers:
const AppError = require('../utils/AppError');

if (!post) throw new AppError('Post not found', 404);
if (!user) throw new AppError('User not found', 404);
if (post.author.toString() !== req.user.id) throw new AppError('Not authorised', 403);

The Async Wrapper (Express 4 Only) #

// server/src/utils/asyncHandler.js
// Wraps an async function so thrown errors are passed to next() automatically
// Not needed in Express 5 — but essential for Express 4

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

module.exports = asyncHandler;

// ── Without asyncHandler (Express 4) — verbose ────────────────────────────────
const getPostById = async (req, res, next) => {
  try {
    const post = await Post.findById(req.params.id);
    if (!post) return next(new AppError('Post not found', 404));
    res.json({ success: true, data: post });
  } catch (err) {
    next(err); // must manually catch and forward every error
  }
};

// ── With asyncHandler (Express 4) — clean ────────────────────────────────────
const asyncHandler = require('../utils/asyncHandler');

const getPostById = asyncHandler(async (req, res) => {
  const post = await Post.findById(req.params.id);
  if (!post) throw new AppError('Post not found', 404); // throw instead of next()
  res.json({ success: true, data: post });
}); // errors automatically forwarded to global error handler ✓

Complete Error Flow — End to End #

Request: GET /api/posts/invalid-id-format

1.  Express matches route: GET /api/posts/:id → getPostById handler
2.  getPostById: await Post.findById('invalid-id-format')
3.  Mongoose throws CastError: Cast to ObjectId failed for value "invalid-id-format"
4.  asyncHandler catches the error → calls next(castError)
5.  Express skips all remaining route/middleware → jumps to errorHandler (4 args)
6.  errorHandler: err.name === 'CastError' && err.kind === 'ObjectId'
    → statusCode = 400, message = 'Invalid ID format: invalid-id-format'
7.  Response sent: 400  { "success": false, "message": "Invalid ID format: invalid-id-format" }

Request: GET /api/posts/nonexistent-but-valid-objectid

1.  Express matches route → getPostById handler
2.  await Post.findById(validId) → returns null (document not found)
3.  throw new AppError('Post not found', 404) → next(appError) via asyncHandler
4.  errorHandler: err.statusCode = 404
    → message = 'Post not found'
5.  Response sent: 404  { "success": false, "message": "Post not found" }

Common Mistakes #

Mistake 1 — Error middleware with only 3 parameters #

❌ Wrong — Express does not recognise it as error middleware:

app.use((err, res, next) => { // missing req — Express sees 3 params → not error middleware!
  res.status(500).json({ message: err.message });
});

✅ Correct — error middleware must have exactly 4 parameters, even if you do not use all of them:

app.use((err, req, res, next) => { // 4 params → Express identifies as error middleware ✓
  res.status(500).json({ message: err.message });
});

Mistake 2 — Registering error middleware before routes #

❌ Wrong — error middleware defined before routes never receives errors from those routes:

app.use(errorHandler);            // registered first — too early
app.use('/api/posts', postsRouter); // errors here bypass errorHandler

✅ Correct — error middleware is always last:

app.use('/api/posts', postsRouter);
app.use(notFound);
app.use(errorHandler); // always last ✓

Mistake 3 — Throwing errors without using next() in Express 4 #

❌ Wrong — throwing inside an async route without asyncHandler causes an unhandled rejection:

app.get('/api/posts/:id', async (req, res) => {
  const post = await Post.findById(req.params.id);
  if (!post) throw new Error('Not found'); // unhandled rejection in Express 4 → crash
});

✅ Correct — wrap with asyncHandler or use try/catch + next(err):

app.get('/api/posts/:id', asyncHandler(async (req, res) => {
  const post = await Post.findById(req.params.id);
  if (!post) throw new AppError('Not found', 404); // safely caught ✓
}));

Quick Reference #