Fix Error: connect ECONNREFUSED 127.0.0.1:5432 in Node.js

This error means Node.js cannot reach the server at the specified address and port, usually because the target service (database, API, etc.) is not running or is listening on a different port. Fix it by verifying the service is started and the host/port configuration matches.

Reading the Stack Trace

Here's what each line means:

• at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1494:16): The TCP connection attempt completed with a refusal, meaning no service was listening on the target port.
• at Object.query (src/db/connection.js:14:22): Your database connection module at line 14 attempted a query that triggered the pool to open a new connection.
• at UserRepository.findAll (src/repositories/userRepository.js:8:30): The repository layer initiated the database call that ultimately failed due to the refused connection.

Common Causes

const { Pool } = require('pg');
const pool = new Pool({
  host: '127.0.0.1',
  port: 5432,
  database: 'myapp',
});
// PostgreSQL is not running
const result = await pool.query('SELECT * FROM users');

const pool = new Pool({
  host: process.env.DB_HOST || '127.0.0.1',
  port: process.env.DB_PORT || 5432,
});
// DB_HOST and DB_PORT env vars are not set, defaults don't match actual server

// docker-compose.yml exposes 5433 externally but app connects to 5432
const pool = new Pool({ host: 'localhost', port: 5432 });

The Fix

Use environment variables for connection config so each environment can specify the correct host and port. Add a connection timeout so the app fails fast instead of hanging. Catch ECONNREFUSED specifically to log a helpful diagnostic message.

const { Pool } = require('pg');
const pool = new Pool({
  host: '127.0.0.1',
  port: 5432,
  database: 'myapp',
});

async function query(text, params) {
  const result = await pool.query(text, params);
  return result;
}

const { Pool } = require('pg');
const pool = new Pool({
  host: process.env.DB_HOST || '127.0.0.1',
  port: parseInt(process.env.DB_PORT, 10) || 5432,
  database: process.env.DB_NAME || 'myapp',
  connectionTimeoutMillis: 5000,
});

async function query(text, params) {
  try {
    const result = await pool.query(text, params);
    return result;
  } catch (err) {
    if (err.code === 'ECONNREFUSED') {
      console.error(`Database connection refused at ${pool.options.host}:${pool.options.port}. Is the server running?`);
    }
    throw err;
  }
}

Testing the Fix

const { query } = require('./connection');

jest.mock('pg', () => {
  const mockQuery = jest.fn();
  const mockPool = { query: mockQuery, options: { host: '127.0.0.1', port: 5432 } };
  return { Pool: jest.fn(() => mockPool), __mockQuery: mockQuery };
});

const { __mockQuery } = require('pg');

describe('Database connection', () => {
  it('returns query results on success', async () => {
    __mockQuery.mockResolvedValue({ rows: [{ id: 1 }] });
    const result = await query('SELECT 1');
    expect(result.rows).toEqual([{ id: 1 }]);
  });

  it('throws and logs on ECONNREFUSED', async () => {
    const err = new Error('connect ECONNREFUSED');
    err.code = 'ECONNREFUSED';
    __mockQuery.mockRejectedValue(err);
    const consoleSpy = jest.spyOn(console, 'error').mockImplementation();
    await expect(query('SELECT 1')).rejects.toThrow('ECONNREFUSED');
    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Database connection refused'));
    consoleSpy.mockRestore();
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/nodejs-econnrefused-handling,git add src/db/connection.js src/db/__tests__/connection.test.js,git commit -m "fix: add ECONNREFUSED error handling and env-based db config",git push origin fix/nodejs-econnrefused-handling

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
        env:
          DB_HOST: localhost
          DB_PORT: 5432

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. Verify the target database service is running and accessible.
2. Update environment variables with the correct host and port.
3. Run the test suite locally to confirm the fix passes.
4. Open a pull request with the changes.
5. Wait for CI to pass and get a teammate review.
6. Merge to main and verify the connection works in staging.

Frequently Asked Questions