How to fix Error: connect ECONNREFUSED 127.0.0.1:5000 (port not listening) in Node.js

Node.jsBEGINNERHIGHUpdated Dec 9, 2025· 353 views

This error occurs when a Node.js application attempts to connect to a TCP port but the connection is actively refused because no service is listening on that port. It commonly happens with database connections, API calls to localhost, or inter-service communication when the target server is not running or the port configuration is incorrect.

Quick fix

Fixes ECONNREFUSED

# Check if any process is listening on the port
lsof -i :5000
# or on Linux
netstat -tuln | grep :5000
# or use ss command
ss -tuln | grep :5000
  1. Verify the target service is running
  2. Confirm the port number matches
  3. Check the host and network interface
  4. Add connection retry logic with delays
node.js — error
# Check if any process is listening on the port
lsof -i :5000
# or on Linux
netstat -tuln | grep :5000
# or use ss command
ss -tuln | grep :5000
Error: connect ECONNREFUSED 127.0.0.1:5000 (port not listening)

What this error means

ECONNREFUSED is a Node.js error code indicating that a TCP connection attempt was actively rejected by the target machine. When your application tries to establish a connection using modules like http, net, or database clients, it sends a TCP SYN packet to the specified host and port. If no process is listening on that port, the operating system responds with a TCP RST (reset) packet, which Node.js translates into this error. This is not a network timeout or DNS resolution failure - it's an explicit refusal from the target system. The error means the network path to the host is working, but nothing is accepting connections on the specified port. This commonly occurs during development when a database server, API server, or microservice hasn't been started yet, or in production when services crash or restart. The error typically includes the IP address and port in the format "ECONNREFUSED 127.0.0.1:5000", making it clear which connection failed. Understanding the distinction between ECONNREFUSED and other connection errors like ETIMEDOUT or ENOTFOUND is crucial for effective troubleshooting.

Typical symptoms

  • Application crashes with "Error: connect ECONNREFUSED 127.0.0.1:PORT"
  • Database connection fails immediately on application startup
  • Fetch or HTTP requests to localhost fail with ECONNREFUSED
  • Docker containers cannot connect to services on host machine
  • Microservices fail to communicate with each other
  • Tests fail because mock server or database is not running
  • Connection errors occur immediately without any timeout delay

Common causes

  1. Target server or database is not running on the specified port
  2. Application is using the wrong port number in connection configuration
  3. Service is listening on a different network interface (e.g., only on 0.0.0.0 but not 127.0.0.1)
  4. Port is already in use by another application, preventing the server from starting
  5. Server crashed or failed to start due to configuration errors
  6. Firewall or security software is blocking the connection
  7. Docker networking misconfiguration when connecting from container to host
  8. Race condition where client tries to connect before server is ready

How to fix "Error: connect ECONNREFUSED 127.0.0.1:5000 (port not listening)"

1Verify the target service is running

Check if the server or database you're trying to connect to is actually running. For a Node.js server:

bash
# Check if any process is listening on the port
lsof -i :5000
# or on Linux
netstat -tuln | grep :5000
# or use ss command
ss -tuln | grep :5000

If no process is listed, the server is not running. Start your server in a separate terminal:

bash
# For a Node.js application
node server.js
# For a development server
npm run dev
# For a database like PostgreSQL
sudo systemctl start postgresql

Ensure the server logs show it's listening on the expected port before attempting connections.

2Confirm the port number matches

Verify that your client code is using the correct port number that the server is actually listening on:

javascript
// Check your connection configuration
const PORT = process.env.PORT || 5000; // Make sure this matches

// For HTTP requests
const response = await fetch(`http://localhost:${PORT}/api`);

// For database connections
const client = new Client({
  host: 'localhost',
  port: 5432, // Ensure this matches your database server
  database: 'mydb'
});

Common mismatches:
- Database clients using default ports (5432 for PostgreSQL, 3306 for MySQL) when server uses custom ports
- Environment variables not loaded correctly
- Different ports in development vs production configurations

3Check the host and network interface

Ensure the server is listening on the correct network interface. A server bound only to 127.0.0.1 won't accept connections from other interfaces:

javascript
// Server binding to all interfaces (accessible from anywhere)
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server running on all interfaces port ${PORT}`);
});

// Server binding only to localhost (only local connections)
app.listen(PORT, '127.0.0.1', () => {
  console.log(`Server running on localhost:${PORT}`);
});

For Docker containers, use 0.0.0.0 to allow connections from the host:

javascript
// In containerized environments
const HOST = '0.0.0.0';
const PORT = 5000;
app.listen(PORT, HOST);

When connecting from outside the container, use localhost or 127.0.0.1 on the host machine if ports are properly mapped.

4Add connection retry logic with delays

Implement retry logic to handle cases where the server takes time to start:

javascript
async function connectWithRetry(url, maxRetries = 5, delay = 1000) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      console.log('Connected successfully');
      return response;
    } catch (err) {
      if (err.code === 'ECONNREFUSED') {
        console.log(`Connection refused, retry ${i + 1}/${maxRetries}`);
        if (i < maxRetries - 1) {
          await new Promise(resolve => setTimeout(resolve, delay));
          delay *= 2; // Exponential backoff
        } else {
          throw new Error('Max retries reached, server not available');
        }
      } else {
        throw err; // Different error, don't retry
      }
    }
  }
}

// Usage
try {
  await connectWithRetry('http://localhost:5000/health');
} catch (err) {
  console.error('Failed to connect:', err.message);
}

This is especially useful in Docker Compose setups where services start in parallel.

5Verify firewall and security settings

Check if firewall rules or security software is blocking the connection:

bash
# Temporarily test with firewall disabled (Linux)
sudo ufw status
sudo ufw allow 5000/tcp

# Windows - check Windows Defender Firewall
# Add inbound rule for your port in Windows Defender settings

# macOS - check if Little Snitch or similar software is blocking

For local development, the firewall typically isn't an issue for localhost connections, but corporate security software or VPNs can interfere.

Also check for proxy settings that might redirect localhost connections:

javascript
// Bypass proxy for localhost in Node.js
process.env.NO_PROXY = 'localhost,127.0.0.1';
6Handle the error gracefully in your code

Add proper error handling to provide clear feedback when connections fail:

javascript
const http = require('http');

const options = {
  hostname: 'localhost',
  port: 5000,
  path: '/api',
  method: 'GET'
};

const req = http.request(options, (res) => {
  console.log(`Status: ${res.statusCode}`);
  res.on('data', (data) => console.log(data.toString()));
});

req.on('error', (err) => {
  if (err.code === 'ECONNREFUSED') {
    console.error('Cannot connect to server on port 5000');
    console.error('Please ensure the server is running');
    console.error('Start it with: npm run server');
  } else {
    console.error('Connection error:', err);
  }
});

req.end();

This makes it immediately clear to developers what action they need to take.

Advanced notes

Docker Networking and Host Connections

When running Node.js in Docker and connecting to services on the host machine, use the special DNS name host.docker.internal instead of localhost:

javascript
// Inside Docker container connecting to host
const dbConfig = {
  host: 'host.docker.internal', // Not 'localhost' or '127.0.0.1'
  port: 5432
};

On Linux, you may need to use the host's network IP or add --add-host=host.docker.internal:host-gateway to your docker run command.

Testing Port Availability Programmatically

Before attempting connections, test if a port is available:

javascript
const net = require('net');

function isPortOpen(port, host = 'localhost', timeout = 2000) {
  return new Promise((resolve) => {
    const socket = new net.Socket();

    socket.setTimeout(timeout);
    socket.once('error', () => resolve(false));
    socket.once('timeout', () => {
      socket.destroy();
      resolve(false);
    });

    socket.connect(port, host, () => {
      socket.end();
      resolve(true);
    });
  });
}

// Usage
if (await isPortOpen(5000)) {
  console.log('Server is ready');
} else {
  console.log('Server is not available');
}

Health Check Endpoints

Implement health check endpoints in your services to verify they're ready:

javascript
// Server-side health check
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok', timestamp: Date.now() });
});

// Client-side health check before connecting
async function waitForServer(url, timeout = 30000) {
  const startTime = Date.now();

  while (Date.now() - startTime < timeout) {
    try {
      const response = await fetch(`${url}/health`);
      if (response.ok) return true;
    } catch (err) {
      // Server not ready yet
    }
    await new Promise(resolve => setTimeout(resolve, 500));
  }
  throw new Error('Server health check timeout');
}

Common Port Conflicts

Be aware of commonly used ports that may conflict:
- 3000: Create React App, many Node.js dev servers
- 5000: Flask (Python), many tutorial examples
- 8000: Django, Python SimpleHTTPServer
- 8080: Alternative HTTP port, Tomcat, many proxies

Use lsof -i :[PORT] or netstat to identify what's using a port.

IPv4 vs IPv6 Issues

Some systems resolve localhost to IPv6 (::1) while servers bind to IPv4 (127.0.0.1):

javascript
// Explicitly use IPv4
const client = new Client({
  host: '127.0.0.1', // Not 'localhost'
  port: 5432
});

// Or configure server to listen on both
server.listen(PORT, '::', () => {
  console.log('Listening on IPv4 and IPv6');
});

Frequently asked questions

What does "ECONNREFUSED" mean?
js error code indicating that a TCP connection attempt was actively rejected by the target machine. When your application tries to establish a connection using modules like http, net, or database clients, it sends a TCP SYN packet to the specified host and port. js translates into this error.
How do I fix "ECONNREFUSED"?
This error occurs when a Node.js application attempts to connect to a TCP port but the connection is actively refused because no service is listening on that port. It commonly happens with database connections, API calls to localhost, or inter-service communication when the target server is not running or the port configuration is incorrect.
What causes "ECONNREFUSED"?
Target server or database is not running on the specified port Application is using the wrong port number in connection configuration Service is listening on a different network interface (e.g., only on 0.0.0.0 but not 127.0.0.1)
Is the "ECONNREFUSED" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading