Error Handling

Catching and responding to errors properly - the error-handling middleware signature, async error patterns, and centralizing error responses.

What it is, in plain English: Error handling in Express centers on a special kind of middleware: a function with FOUR parameters (err, req, res, next), which Express recognizes as an error handler and skips for normal requests. Errors reach it either by calling next(err) explicitly, or (in Express 5) automatically when an async route handler throws or rejects. Centralizing error handling in one place keeps every route from repeating the same try/catch and response-formatting logic.

Centralizing how your app responds to errors

The error-handling middleware signature

// A middleware function with FOUR parameters is special -- Express
// recognises it as an error handler and routes errors to it:
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: "Something went wrong" });
});

// This MUST be registered LAST, after all your routes:
app.get("/", homeHandler);
app.get("/users", usersHandler);
app.use((err, req, res, next) => { /* error handler */ });   // last

Triggering the error handler -- next(err)

app.get("/users/:id", (req, res, next) => {
  const user = findUser(req.params.id);
  if (!user) {
    const err = new Error("User not found");
    err.statusCode = 404;
    return next(err);   // passes the error to the error-handling middleware
  }
  res.json(user);
});

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

The 404 handler -- for routes that don't exist

// Place this AFTER all your real routes, BEFORE the error handler:
app.get("/", homeHandler);
app.get("/users", usersHandler);

// Catches anything that didn't match any route above:
app.use((req, res) => {
  res.status(404).json({ error: "Route not found" });
});

app.use((err, req, res, next) => {   // the actual error handler, last
  res.status(500).json({ error: err.message });
});

Async errors -- Express 4 vs Express 5

// Express 4 -- errors thrown in async functions are NOT caught automatically:
app.get("/users/:id", async (req, res, next) => {
  try {
    const user = await db.users.findById(req.params.id);
    res.json(user);
  } catch (err) {
    next(err);   // MUST manually catch and forward
  }
});

// Express 5 -- catches them automatically, no try/catch needed:
app.get("/users/:id", async (req, res) => {
  const user = await db.users.findById(req.params.id);   // if this throws, Express 5 catches it
  res.json(user);
});

Try It Yourself (Node.js logic)

// Error handling middleware -- the 4-argument signature

// A custom error class with a status code attached
class AppError extends Error {
  constructor(message, statusCode = 500) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = true;  // distinguishes expected errors from bugs
  }
}

class NotFoundError extends AppError {
  constructor(resource) {
    super(`${resource} not found`, 404);
  }
}

class ValidationError extends AppError {
  constructor(message) {
    super(message, 400);
  }
}

// Simulating route handlers that can throw these errors:
function findUser(id) {
  const users = { "1": { id: "1", name: "Alice" } };
  const user = users[id];
  if (!user) throw new NotFoundError("User");
  return user;
}

function validateEmail(email) {
  if (!email.includes("@")) throw new ValidationError("Invalid email format");
  return true;
}

// Simulating the error-handling middleware logic:
function errorHandler(err, req) {
  console.log(`[ERROR] ${err.statusCode || 500}: ${err.message}`);
  if (!err.isOperational) {
    console.log("  (Unexpected error -- would log full stack trace and alert)");
  }
  return {
    status: err.statusCode || 500,
    body: { error: err.message },
  };
}

// Demonstrate the pattern:
try {
  findUser("999");
} catch (err) {
  const response = errorHandler(err);
  console.log("Response:", JSON.stringify(response));
}

try {
  validateEmail("not-an-email");
} catch (err) {
  const response = errorHandler(err);
  console.log("Response:", JSON.stringify(response));
}

try {
  throw new Error("Database connection lost");  // unexpected error, not operational
} catch (err) {
  const response = errorHandler(err);
  console.log("Response:", JSON.stringify(response));
}

Custom error classes and a wrapper for Express 4

A custom error class hierarchy

class AppError extends Error {
  constructor(message, statusCode) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = true;   // "expected" errors vs unexpected bugs
    Error.captureStackTrace(this, this.constructor);
  }
}

class NotFoundError extends AppError {
  constructor(resource = "Resource") { super(`${resource} not found`, 404); }
}
class ValidationError extends AppError {
  constructor(message) { super(message, 400); }
}
class UnauthorizedError extends AppError {
  constructor(message = "Unauthorized") { super(message, 401); }
}

// Usage in routes -- throw, don't manually build status codes everywhere:
app.get("/users/:id", async (req, res, next) => {
  try {
    const user = await db.users.findById(req.params.id);
    if (!user) throw new NotFoundError("User");
    res.json(user);
  } catch (err) { next(err); }
});

The asyncHandler wrapper (Express 4 pattern)

// Eliminates repetitive try/catch in every async route:
function asyncHandler(fn) {
  return (req, res, next) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
}

// Before:
app.get("/users/:id", async (req, res, next) => {
  try {
    const user = await db.users.findById(req.params.id);
    res.json(user);
  } catch (err) { next(err); }
});

// After -- the wrapper handles the catch automatically:
app.get("/users/:id", asyncHandler(async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) throw new NotFoundError("User");
  res.json(user);
}));

The centralized error handler, fully fleshed out

function errorHandler(err, req, res, next) {
  const statusCode = err.statusCode ?? 500;
  const isOperational = err.isOperational ?? false;

  if (!isOperational) {
    console.error("UNEXPECTED ERROR:", err);   // log full details, alert monitoring
  }

  res.status(statusCode).json({
    error: isOperational ? err.message : "Internal server error",
    // never leak internal error details to the client for unexpected errors
  });
}

app.use(errorHandler);

Process-level error handling and graceful shutdown

// Express's error middleware only catches errors INSIDE the request cycle.
// Errors outside it (startup failures, unhandled promise rejections elsewhere)
// need process-level handlers:

process.on("uncaughtException", (err) => {
  console.error("UNCAUGHT EXCEPTION! Shutting down...", err);
  process.exit(1);   // mandatory -- the process is in an undefined state after this
});

process.on("unhandledRejection", (reason) => {
  console.error("UNHANDLED REJECTION! Shutting down...", reason);
  server.close(() => process.exit(1));   // graceful: finish in-flight requests first
});

// Graceful shutdown on deployment/restart signals:
process.on("SIGTERM", () => {
  console.log("SIGTERM received, closing server gracefully");
  server.close(() => {
    db.disconnect();
    process.exit(0);
  });
});

Operational vs programmer errors -- the distinction that matters

The isOperational flag pattern distinguishes two fundamentally different error categories. Operational errors are expected runtime problems — a user requesting a resource that doesn't exist, invalid input, a failed database connection — situations your application should anticipate and handle gracefully with a clear client-facing message. Programmer errors are bugs — a typo, calling a function with the wrong arguments, a null reference. These should NOT be caught and continued past silently; the safest response to an unexpected programmer error is often to log it, alert, and let the process restart (via a process manager like PM2 or a container orchestrator), since the application's in-memory state may now be inconsistent in ways that are hard to reason about.

Official Sources

The Codex links only to official documentation. No third-party tutorials.