Fix ServiceUnavailableError: Response timeout — service took too long to respond in Express

This error occurs when an Express route handler takes longer than the configured timeout to send a response, typically due to a slow database query, external API call, or blocking operation. Fix it by setting appropriate timeouts, using the connect-timeout middleware, and ensuring long-running tasks are processed asynchronously.

Reading the Stack Trace

Here's what each line means:

• at IncomingMessage.<anonymous> (/app/node_modules/connect-timeout/index.js:55:17): The connect-timeout middleware detected the response was not sent within the configured timeout period.
• at Timeout._onTimeout (/app/node_modules/connect-timeout/index.js:49:11): The Node.js timer fired, indicating the timeout threshold has been exceeded for this request.
• at generateReport (/app/src/routes/reports.js:22:18): The report generation handler at line 22 is performing a long-running operation that exceeded the timeout.

Common Causes

app.get('/api/reports', async (req, res) => {
  // This query can take 30+ seconds on large datasets
  const data = await db.query('SELECT * FROM reports WHERE created_at > $1', [req.query.since]);
  res.json(data.rows);
});

app.get('/api/weather', async (req, res) => {
  const response = await fetch('https://api.weather.example.com/forecast');
  const data = await response.json();
  res.json(data);
});

app.get('/api/compute', (req, res) => {
  // CPU-intensive synchronous operation blocks the event loop
  const result = heavyComputation(req.query.input);
  res.json({ result });
});

The Fix

Add the connect-timeout middleware with a 15-second limit. Check req.timedout before sending responses to avoid writing to an already-closed connection. Add a LIMIT clause to the database query to prevent unbounded result sets, and handle timeout errors with a 503 response.

app.get('/api/reports', async (req, res) => {
  const data = await db.query('SELECT * FROM reports WHERE created_at > $1', [req.query.since]);
  res.json(data.rows);
});

const timeout = require('connect-timeout');

app.use(timeout('15s'));

app.get('/api/reports', async (req, res, next) => {
  try {
    const data = await db.query(
      'SELECT * FROM reports WHERE created_at > $1 LIMIT 1000',
      [req.query.since]
    );
    if (!req.timedout) {
      res.json(data.rows);
    }
  } catch (err) {
    if (!req.timedout) {
      next(err);
    }
  }
});

app.use((err, req, res, next) => {
  if (req.timedout) {
    return res.status(503).json({
      error: 'Service Unavailable',
      message: 'The request took too long to process. Please try again.'
    });
  }
  next(err);
});

Testing the Fix

const request = require('supertest');
const express = require('express');
const timeout = require('connect-timeout');

function createApp(queryDelay) {
  const app = express();
  app.use(timeout('500ms')); // Short timeout for testing
  app.get('/api/reports', async (req, res, next) => {
    try {
      await new Promise(resolve => setTimeout(resolve, queryDelay));
      if (!req.timedout) {
        res.json({ reports: [] });
      }
    } catch (err) {
      if (!req.timedout) next(err);
    }
  });
  app.use((err, req, res, next) => {
    if (req.timedout) {
      return res.status(503).json({ error: 'Service Unavailable' });
    }
    next(err);
  });
  return app;
}

describe('Request timeout', () => {
  it('returns 200 for fast responses', async () => {
    const res = await request(createApp(50)).get('/api/reports');
    expect(res.status).toBe(200);
    expect(res.body.reports).toEqual([]);
  });

  it('returns 503 when request times out', async () => {
    const res = await request(createApp(1000)).get('/api/reports');
    expect(res.status).toBe(503);
    expect(res.body.error).toBe('Service Unavailable');
  });
});

Run your tests:

npx jest --testPathPattern=timeout

Pushing Through CI/CD

git checkout -b fix/express-timeout-error,git add src/middleware/timeout.js src/routes/reports.js src/__tests__/timeout.test.js,git commit -m "fix: add connect-timeout middleware and check req.timedout",git push origin fix/express-timeout-error

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: npx jest --coverage
      - 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 confirm timeout scenarios return 503.
2. Open a pull request with the timeout middleware and query optimization.
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 response times in staging before promoting to production.

Frequently Asked Questions