⚡ Asynchronous Error Handling

The Challenge of Async Errors

Synchronous errors travel up the call stack and land in Express's error middleware. Asynchronous errors do not — by the time a database call rejects, the function that started it has already returned and its stack frame is gone. The error has nowhere to bubble to.

💡 A mental picture: A synchronous error is a ball dropped down a chute — gravity delivers it to the bottom. An async error is a ball thrown after the person holding the chute has already walked away. Nobody is there to catch it unless you arrange for a catcher in advance.

The consequences are concrete: in Express 4, an unhandled rejection in a route means the request hangs forever (the client eventually times out) and Node logs an UnhandledPromiseRejection warning that can crash the process on newer runtimes.

Why Express Misses Them

Express 4's middleware system predates promises and async/await. Its try/catch wraps only the synchronous call to your handler. Look closely:

function handler(req, res, next) {
  throw new Error('sync');            // Caught — Express wraps this call

  setTimeout(() => {
    throw new Error('async');         // NOT caught — different tick, no stack
  }, 100);

  Promise.reject(new Error('promise')); // NOT caught — rejection, not a throw
}

An async function always returns a promise. When it rejects, there is no throw for Express 4 to intercept — the framework simply never learns the request failed. That is the gap every solution below fills: getting the rejection back to next().

Handling Callback Errors

Plenty of older libraries still use Node's error-first callback style. There is no magic here — you check the error and forward it yourself:

app.get('/users/:id', (req, res, next) => {
  db.getUser(req.params.id, (err, user) => {
    if (err) return next(err);                // Forward DB errors
    if (!user) return next(new NotFoundError('User'));
    res.json(user);
  });
});

Better still, stop writing callbacks. Node's built-in util.promisify converts any error-first callback function into one that returns a promise, so you can use it with async/await:

const { promisify } = require('node:util');

const getUser = promisify(db.getUser); // now returns a promise

app.get('/users/:id', async (req, res, next) => {
  try {
    const user = await getUser(req.params.id);
    if (!user) return next(new NotFoundError('User'));
    res.json(user);
  } catch (err) {
    next(err);
  }
});

The catchAsync Wrapper

Writing try/catch in every async route is noise. The classic fix is a tiny higher-order function that wraps a handler, runs it, and pipes any rejection straight to next:

// utils/catchAsync.js
const catchAsync = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

module.exports = catchAsync;

Promise.resolve() makes it work whether your handler returns a promise or not, and .catch(next) forwards any rejection. Now routes are clean:

const catchAsync = require('../utils/catchAsync');

app.get('/users/:id', catchAsync(async (req, res, next) => {
  const user = await User.findById(req.params.id);
  if (!user) throw new NotFoundError('User');   // Rejection forwarded for you
  res.json(user);
}));

You can even wrap a whole router so every handler is covered automatically:

// utils/asyncRouter.js
const express = require('express');
const catchAsync = require('./catchAsync');

function asyncRouter() {
  const router = express.Router();
  for (const method of ['get', 'post', 'put', 'patch', 'delete']) {
    const original = router[method].bind(router);
    router[method] = (path, ...handlers) =>
      original(path, ...handlers.map(h =>
        h.length === 4 ? h : catchAsync(h)   // leave error middleware alone
      ));
  }
  return router;
}

module.exports = asyncRouter;

Express 5's Built-in Support

Here's the good news: Express 5 (the current major version, released in 2024) fixes this at the framework level. A rejected promise returned from an async handler is automatically forwarded to your error middleware — no wrapper required.

// Express 5 — this rejection reaches your error handler automatically
app.get('/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) throw new NotFoundError('User');
  res.json(user);
});

Domain Error Classes

As an app grows, generic errors blur together. Organizing errors by domain — user, order, payment — keeps intent obvious and lets services throw meaningful types the handler can recognize:

// domains/user/errors.js
const { AppError } = require('../../errors');

class UserNotFoundError extends AppError {
  constructor(userId) {
    super(`User ${userId} not found`, 404, 'USER_NOT_FOUND');
  }
}

class UserValidationError extends AppError {
  constructor(details) {
    super('User validation failed', 400, 'USER_VALIDATION_FAILED');
    this.details = details;
  }
}

module.exports = { UserNotFoundError, UserValidationError };

The service layer throws them; the route stays thin; the central handler already knows what to do because they all extend AppError:

// domains/user/service.js
class UserService {
  async getUser(id) {
    const user = await db.getUser(id);
    if (!user) throw new UserNotFoundError(id);
    return user;
  }
}

// routes/userRoutes.js
router.get('/users/:id', catchAsync(async (req, res) => {
  const user = await userService.getUser(req.params.id);
  res.json(user);
}));

Global Safety Nets

Even with perfect route handling, something may reject where no catch can reach it — a stray timer, a background job, a bug. Node gives you two process-level events as a last resort. Treat them as a signal to log and restart, not to keep running in an unknown state.

// Synchronous bugs that escaped everything — the app is now unreliable
process.on('uncaughtException', (err) => {
  console.error('UNCAUGHT EXCEPTION! Shutting down.');
  console.error(err.name, err.message);
  process.exit(1); // let your process manager (pm2, Docker, etc.) restart
});

// A rejected promise nobody caught
process.on('unhandledRejection', (reason) => {
  console.error('UNHANDLED REJECTION! Shutting down.');
  console.error(reason);
  // Finish in-flight requests, then exit
  server.close(() => process.exit(1));
});

Hands-on Exercise

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

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

async function getUser(id) {
  if (id === '0') throw Object.assign(new Error('DB connection lost'), { statusCode: 503 });
  return { id, name: 'Ada' };
}

app.get('/users/:id', catchAsync(async (req, res) => {
  const user = await getUser(req.params.id);
  res.json(user);
}));

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

app.listen(3000, () => console.log('http://localhost:3000'));
// GET /users/0  -> 503 { "error": { "message": "DB connection lost" } }
// GET /users/7  -> 200 { "id": "7", "name": "Ada" }

Summary & Quiz

📚 Further Reading

• Express — Error Handling (async section)
• Node.js — Errors documentation
• Node.js — unhandledRejection event

🚀 What's Next?

Your app now catches errors from every corner. Next we turn to error response strategies: designing a consistent JSON envelope, choosing the right status codes, and shaping responses that clients — and other developers — can rely on.