Fix UnhandledPromiseRejection: Unhandled promise rejection in async route handler in Express

This error occurs when an async Express route handler throws an error that is not caught. Express does not natively catch promise rejections from async functions, causing the process to crash. Fix it by wrapping async handlers in a try-catch block or using an async error-handling wrapper middleware.

Reading the Stack Trace

Here's what each line means:

• triggerUncaughtException(err, true /* fromPromise */);: Node.js detected an unhandled promise rejection and is about to crash the process.
• at getUsers (/app/src/routes/users.js:12:11): The async getUsers handler threw at line 12 without a try-catch, so the rejection went unhandled.
• at Layer.handle [as handle_request] (/app/node_modules/express/lib/router/layer.js:95:5): Express router layer does not await async handlers, so thrown errors are not forwarded to error middleware.

Common Causes

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

router.get('/users', (req, res) => {
  db.query('SELECT * FROM users').then(users => {
    res.json(users);
  });
});

The Fix

Wrap every async route handler with an asyncHandler utility that catches rejected promises and forwards them to Express error middleware via next(err). This prevents unhandled rejections and returns proper error responses.

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

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

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

// Error-handling middleware (in app.js)
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: 'Internal server error' });
});

Testing the Fix

const request = require('supertest');
const express = require('express');

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

describe('GET /users', () => {
  let app;

  beforeEach(() => {
    app = express();
  });

  it('returns 500 when the database query fails', async () => {
    app.get('/users', asyncHandler(async (req, res) => {
      throw new Error('Database query failed');
    }));
    app.use((err, req, res, next) => {
      res.status(500).json({ error: err.message });
    });

    const response = await request(app).get('/users');
    expect(response.status).toBe(500);
    expect(response.body.error).toBe('Database query failed');
  });

  it('returns users on success', async () => {
    app.get('/users', asyncHandler(async (req, res) => {
      res.json([{ id: 1, name: 'Alice' }]);
    }));

    const response = await request(app).get('/users');
    expect(response.status).toBe(200);
    expect(response.body).toHaveLength(1);
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/unhandled-promise-rejection,git add src/middleware/asyncHandler.js src/routes/users.js,git commit -m "fix: wrap async route handlers to catch promise rejections",git push origin fix/unhandled-promise-rejection

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test
      - run: npm run lint

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

const { initBugStack } = require('bugstack-sdk')

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Run the test suite locally to verify error handling works for all async routes.
2. Open a pull request with the asyncHandler wrapper and error middleware.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and monitor error rates in production to confirm the fix.

Frequently Asked Questions