Diagnosing and Fixing Unhandled Promise Rejections in Express Routes

Problem

When an async route handler throws or returns a rejected promise, you may see one of the following:

• Client request times out or receives no response.
• Server responds with a generic 500 status but no stack trace.
• Node process exits immediately due to an unhandled rejection.

These symptoms indicate that Express did not capture the rejection and forward it to the error‑handling middleware.

Recognizable Condition

Send a request to an async route that intentionally throws an error and observe the server’s behavior. If the request hangs or the process dies, you’re in the diagnostic loop.

Common Causes

| Cause | Express 4.x | Express 5.x | |---|---|---| | Async handler returns a rejected promise | Not caught; propagates to Node’s unhandledRejection | Automatically caught and forwarded to next(err) | | Missing error‑handling middleware | Default 500 response or no response | Default 500 response | | Error middleware registered before routes | Errors bypass middleware | Errors bypass middleware | | Wrapper that discards this or context | Breaks route logic | Breaks route logic | | Node configured to exit on unhandledRejection | Causes crash | No effect (Express handles it) | | Using Express 5.x in production without alpha‑flags | N/A | Potential breaking changes |

Ordered Checks

1. Verify Express version
   Run npm list express to confirm you’re on 4.x or 5.x.
2. Test the route in isolation
   Use curl -i http://localhost:3000/test after adding app.get('/test', async (req, res) => { throw new Error('boom'); });.
3. Observe process behavior
   Check if the request hangs, a 500 is sent, or the Node process exits.
4. Check for unhandledRejection listener
   Run node -e "process.on('unhandledRejection', r=>console.log('unhandled', r)); require('./app');" to see if the rejection reaches Node.
5. Confirm error middleware order
   Ensure app.use((err, req, res, next) => { /* log & send */ }); is added after all routes.
6. Check wrapper usage
   If a helper like asyncHandler is used, verify it preserves this and arguments.
7. Validate Express 5.x alpha flag
   When using express@next, confirm process.env.EXPRESS_DEBUG=1 is set if you want verbose logs.

Fixes Tied to Findings

1. Express 4.x – Wrap Async Handlers

Express 4.x does not automatically catch promise rejections. Wrap each async handler:

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

app.get('/data', asyncHandler(async (req, res) => {
  const data = await db.fetch();
  res.json(data);
}));

Benefits:

• Single place to handle errors.
• Preserves this via arrow function binding.
• Works with any promise‑returning middleware.

2. Express 4.x – Add Global UnhandledRejection Listener

To avoid silent crashes, add a listener that logs and exits on unhandled rejections:

process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
  process.exit(1);
});

Use this only if you prefer Node to terminate rather than silently ignoring the error.

3. Express 5.x – No Wrapper Needed

Express 5.x automatically forwards rejected promises. Declare the route as async and add standard error middleware:

app.get('/data', async (req, res) => {
  const data = await db.fetch();
  res.json(data);
});

// Error middleware must come last
app.use((err, req, res, next) => {
  console.error(err);
  res.status(500).json({ error: err.message });
});

Remember that Express 5.x is still alpha; enable it with npm install express@next and set process.env.EXPRESS_DEBUG=1 for verbose output.

4. Ensure Middleware Order

Express processes middleware in the order it’s defined. Place error middleware after all routes and other middleware:

app.use(express.json());
app.use('/api', apiRouter); // routes
app.use((err, req, res, next) => { /* error handling */ });

If placed before routes, errors will never reach it.

5. Preserve Context in Wrappers

A naive wrapper that ignores this can break handlers that reference this.app or similar. Use arrow functions or bind this explicitly:

const asyncHandler = fn => function (req, res, next) {
  Promise.resolve(fn.call(this, req, res, next)).catch(next);
};

Escalation Criteria

• If the request still times out after applying the wrapper, check network latency or database timeouts.
• If the process continues to crash on every unhandled rejection, remove the unhandledRejection listener and rely on Express’s built‑in handling (4.x wrapper or 5.x auto).
• If you’re on Express 5.x alpha and encounter unexpected behavior, downgrade to 4.x until the stable release is available.
• When using third‑party middleware that returns promises, confirm it also forwards errors via next() or use the global wrapper pattern.

Practical Verification

1. Create a minimal app (app.js):

   const express = require('express');
   const app = express();
   
   // Async route that throws
   app.get('/test', async (req, res) => { throw new Error('boom'); });
   
   // Error middleware
   app.use((err, req, res, next) => {
     console.error('Error caught:', err.message);
     res.status(500).json({ error: err.message });
   });
   
   app.listen(3000, () => console.log('Server ready'));
   

2. Run node app.js and request http://localhost:3000/test. In Express 4.x you’ll see a crash or timeout; in Express 5.x you’ll get a 500 JSON response.
3. Apply the asyncHandler wrapper and re‑run. The 500 response should now appear consistently in 4.x.
4. Add process.on('unhandledRejection', …) and observe the console output when the route throws.

Limitations & Caveats

• Express 5.x is alpha; use it only in controlled environments.
• Global unhandledRejection listeners may mask errors that Express would otherwise surface.
• Wrapping every async handler increases boilerplate; consider a lint rule or a custom wrapper library for consistency.
• Ensure the wrapper does not alter the stack trace; use Promise.resolve to preserve original error.

Takeaway

In Express 4.x, unhandled promise rejections in route handlers are silent bugs that can cause hangs or crashes. Wrap async handlers or upgrade to Express 5.x, which adds automatic promise handling. Always place error middleware after routes, preserve context in wrappers, and be cautious when using alpha releases. Following the ordered checks and fixes above will give you a reliable error‑handling path for both current and future Express versions.