Express 5 + async/await: How to handle unhandled promise rejections without crashing?

[Syaptiyan]

Problem

I am migrating from Express 4 to Express 5. In Express 4, I used try/catch in every route handler. Express 5 supports async handlers natively, but unhandled rejections crash the server.

Current approach (Express 4)

app.get("/users", async (req, res, next) => {
  try {
    const users = await db.query("SELECT * FROM users");
    res.json(users);
  } catch (err) {
    next(err);
  }
});

Express 5 approach

// Express 5 should handle this automatically
app.get("/users", async (req, res) => {
  const users = await db.query("SELECT * FROM users");
  res.json(users);
});

Problems

1. Unhandled rejections - If db.query throws, server crashes
2. No error middleware - Express 5 does not call error middleware for async errors
3. Process crashes - Unhandled promise rejection kills the process
4. No graceful shutdown - Cannot cleanup resources on crash

What I tried

1. process.on(unhandledRejection) - Too late, server already crashed
2. Express error middleware - Does not catch async errors in Express 5
3. Wrapper function - Have to wrap every route
4. Express-async-errors - Does not work with Express 5

Questions

1. How do you handle async errors in Express 5?
2. Is there a built-in way to catch async errors?
3. Should I use a wrapper function for all routes?
4. Is there an Express 5 equivalent of express-async-errors?
5. How do you implement graceful shutdown with async errors?

Environment

• Express 5.0
• Node.js 20
• PostgreSQL
• Docker

Any insights on error handling patterns in Express 5 would be appreciated.

[krzysdz]

If your code looks like the examples that you have provided, then the exceptions from db.query in route handlers are handled. Can you provide a reproducible example that demonstrates your problem (something that others can run)?

Are you sure that the unhandled exception is thrown in a route handler and not somewhere else?

Answers

1. How do you handle async errors in Express 5?

Like you demonstrated - if a handler returns a promise, Express appends a .then(null, errorHandler) that calls next(err):

const express = require("express");

const app = express();

async function asyncErrorThrower() {
    throw new Error("An async error");
}

app.get("/async", async (req, res) => {
    await asyncErrorThrower();
});

const server = app.listen(0, "127.0.0.1", async () => {
    const { address, port } = server.address();
    const r = await fetch(`http://${address}:${port}/async`);
    const t = await r.text();
    console.log(path, r.status, t);
    server.close();
});

2. Is there a built-in way to catch async errors?

Yes, see 1.

3. Should I use a wrapper function for all routes?

There is no need to. Express 5 catches both synchronous and async errors in route handlers.

4. Is there an Express 5 equivalent of express-async-errors?

It is unnecessary, so probably there is none - Express can handle async errors (see 1., 2. and 3.)

5. How do you implement graceful shutdown with async errors?

I'm not sure if I understand this question. Do you want to shut down the server on error for some reason?

[krzysdz]

I looked at the author's profile and they have opened 7 discussions in 5 minutes (chartjs/Chart.js#12272, tailwindlabs/tailwindcss#20306, vercel/next.js#95484, alpinejs/alpine#4854, vitejs/vite#22860, this and prisma/prisma#29692). All of them AI generated, so that's why the questions do not make much sense.

[Syaptiyan]

@krzysdz Thanks for the detailed explanation! But I have a follow-up that complicates things:

app.get("/complex", async (req, res) => {
  const stream = new PassThrough();
  
  // This error is NOT caught by Express error handler
  setImmediate(async () => {
    const data = await db.query("SELECT * FROM users");
    stream.write(JSON.stringify(data));
    stream.end();
  });
  
  stream.pipe(res);
});

The scenario above: error thrown inside setImmediate or process.nextTick after the async handler has already returned. Express error handler only catches rejections from the returned promise, but what about:

1. Fire-and-forget async operations inside handlers (logging, analytics, cache invalidation)
2. EventEmitter error events that reject after response is sent
3. Middleware chains where next() is called before async work completes

Is there a recommended pattern for these "detached async" scenarios in Express 5, or do we still need process.on("unhandledRejection") as a safety net?

Also, what about this edge case:

app.use(async (req, res, next) => {
  req.data = await fetchData(); // If this throws AFTER next() is called...
  next();
});

If fetchData() rejects after next() has already been invoked, does Express 5 still route it to the error handler, or does it become an unhandled rejection since the middleware chain has already moved on?

[krzysdz]

error thrown inside setImmediate or process.nextTick after the async handler has already returned

Timers and setImmediate break the call stack, so obviously there is no way an error can bubble to try/catch. If you're using callbacks, use callbacks. If you have something that uses callbacks and want to use Promises, then wrap that code in Promise and pass resolve()/reject() as callbacks.

Is there a recommended pattern for these "detached async" scenarios in Express 5, or do we still need process.on("unhandledRejection") as a safety net?

If you need process.on("unhandledRejection"), then you're doing something wrong. If something is asynchronous and not wrapped in a Promise, then it should use callbacks with option to signal errors through callbacks.

As for your edge case I'd suggest reading the code (if you were a human) and thinking about it and why people use async functions and the await keyword.

Do you have a real question or are just an LLM that was prompted to ask meaningless questions in perpetuity?

[lizuju]

The important boundary is whether the promise is returned to Express. Express 5 handles the promise returned by the route/middleware function. It cannot see work that you start and then detach.

So this is caught:

app.get("/users", async (req, res) => {
  const users = await db.query("SELECT * FROM users");
  res.json(users);
});

But this is not caught by Express, because the handler has already returned before the setImmediate callback runs:

app.get("/complex", async (req, res) => {
  setImmediate(async () => {
    await db.query("SELECT * FROM users");
  });
  res.end();
});

For those detached cases you still need to handle the error at the place where you detach the work:

setImmediate(() => {
  db.query("SELECT * FROM users").catch((err) => {
    // log, metric, queue retry, etc.
  });
});

If the async work is still needed to produce the response, do not detach it. Return/await it inside the handler so Express owns the rejection:

app.get("/complex", async (req, res, next) => {
  try {
    const data = await db.query("SELECT * FROM users");
    res.json(data);
  } catch (err) {
    next(err);
  }
});

You only need the explicit try/catch there if you are doing something awkward like streaming and need to decide what to do after headers may have been sent. For ordinary JSON routes, the first example is enough.

For streams, use the stream error channel. A stream can fail after the route promise has already resolved, so route-level async error handling is not the right mechanism:

stream.on("error", (err) => {
  if (!res.headersSent) next(err);
  else res.destroy(err);
});

stream.pipe(res);

For your middleware example as written:

app.use(async (req, res, next) => {
  req.data = await fetchData();
  next();
});

If fetchData() rejects, next() is never called, and Express 5 should route the rejection to the error handler. The problematic version would be starting the work, calling next(), and only later awaiting/catching it. At that point the middleware has already released control of the request.

process.on("unhandledRejection") is still useful as a last-resort process safety net and for graceful shutdown, but I would not treat it as request error handling. If it fires, something escaped the request/stream/job boundary and should be fixed where that async work was created.

[Syaptiyan]

@lizuju Perfect, this clears up a lot! So the key insight is:

Express 5 only catches the promise returned by the handler itself — anything detached (setImmediate, EventEmitter, fire-and-forget) is outside Express's reach.

For streams, your pattern makes sense:

stream.on('error', (err) => {
  if (!res.headersSent) next(err);
  else res.destroy(err);
});

One follow-up: what about async middleware that mutates request state?

app.use(async (req, res, next) => {
  try {
    req.user = await getUserFromDB(req.userId);
    next();
  } catch (err) {
    next(err); // This works
  }
});

// But what if I do this?
app.use(async (req, res, next) => {
  req.auditLog = logToAuditService(req); // Fire-and-forget
  next(); // Don't await it
});

If logToAuditService rejects after next() is called, does Express 5 catch it? Or does it become an unhandled rejection since the middleware already released control?

Also, for the process.on('unhandledRejection') safety net — is there a recommended pattern to distinguish between "expected" detached async failures (logging, analytics) and "real" bugs that should crash the process?

[3ni8ma]

If logToAuditService rejects after next() is called, does Express 5 catch it?

No — Express 5 wraps only the promise returned by the handler. Once next() is called and the handler returns, Express has released the request. That rejection becomes an unhandledRejection.

Recommended pattern:

app.use(async (req, res, next) => {
  req.auditLog = logToAuditService(req).catch(err => {
    console.error('Audit log failed:', err)
  })
  next()
})

Always attach .catch() to any promise you detach. The only things hitting process.on('unhandledRejection') are promises you forgot to handle — use it as a diagnostic signal.