Fix Error: connect ECONNREFUSED 127.0.0.1:5000 in Express

This error occurs when http-proxy-middleware or a similar proxy tries to forward a request to an upstream server that is not running or is unreachable. The TCP connection is refused because nothing is listening on the target port. Fix it by verifying the upstream service is running, adding health checks, and handling proxy errors gracefully.

Reading the Stack Trace

Here's what each line means:

• at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1595:16): The TCP connection attempt to 127.0.0.1:5000 was refused because no process is listening on that port.
• at ClientRequest.<anonymous> (/app/node_modules/http-proxy/lib/http-proxy/passes/web-incoming.js:172:24): The http-proxy library attempted to forward the incoming request to the target server and received the connection refusal.
• at Socket.socketErrorListener (node:_http_client:500:9): Node's HTTP client detected the socket error and is propagating it up through the proxy middleware.

Common Causes

const { createProxyMiddleware } = require('http-proxy-middleware');

app.use('/api', createProxyMiddleware({
  target: 'http://localhost:5000',
  changeOrigin: true
}));

// Backend on port 5000 is not running

app.use('/api', createProxyMiddleware({
  target: 'http://localhost:5000', // Should be port 5001
  changeOrigin: true
}));

app.use('/api', createProxyMiddleware({
  target: 'http://localhost:5000',
  changeOrigin: true
  // No onError handler
}));

The Fix

Add an onError handler to the proxy middleware that catches ECONNREFUSED and other connection errors, returning a 502 Bad Gateway response instead of crashing. Use an environment variable for the target URL to avoid hardcoding.

const { createProxyMiddleware } = require('http-proxy-middleware');

app.use('/api', createProxyMiddleware({
  target: 'http://localhost:5000',
  changeOrigin: true
}));

const { createProxyMiddleware } = require('http-proxy-middleware');

app.use('/api', createProxyMiddleware({
  target: process.env.API_TARGET || 'http://localhost:5000',
  changeOrigin: true,
  on: {
    error: (err, req, res) => {
      console.error('Proxy error:', err.code, err.message);
      if (!res.headersSent) {
        res.status(502).json({
          error: 'Bad Gateway',
          message: 'The upstream service is unavailable. Please try again later.'
        });
      }
    }
  }
}));

Testing the Fix

const request = require('supertest');
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');
const http = require('http');

function createApp(target) {
  const app = express();
  app.use('/api', createProxyMiddleware({
    target,
    changeOrigin: true,
    on: {
      error: (err, req, res) => {
        if (!res.headersSent) {
          res.status(502).json({ error: 'Bad Gateway' });
        }
      }
    }
  }));
  return app;
}

describe('Proxy middleware', () => {
  it('returns 502 when upstream is unreachable', async () => {
    const res = await request(createApp('http://localhost:59999'))
      .get('/api/data');
    expect(res.status).toBe(502);
    expect(res.body.error).toBe('Bad Gateway');
  });

  it('proxies successfully when upstream is available', async () => {
    const upstream = http.createServer((req, res) => {
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ proxied: true }));
    });
    await new Promise(resolve => upstream.listen(0, resolve));
    const port = upstream.address().port;
    const res = await request(createApp(`http://localhost:${port}`))
      .get('/api/data');
    expect(res.status).toBe(200);
    expect(res.body.proxied).toBe(true);
    upstream.close();
  });
});

Run your tests:

npx jest --testPathPattern=proxy

Pushing Through CI/CD

git checkout -b fix/express-proxy-error,git add src/middleware/proxy.js src/__tests__/proxy.test.js,git commit -m "fix: add error handler for proxy ECONNREFUSED",git push origin fix/express-proxy-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 proxy errors return 502 instead of crashing.
2. Open a pull request with the proxy error handling changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify the proxy works in staging before promoting to production.

Frequently Asked Questions