ECONNREFUSED

What is ECONNREFUSED?

ECONNREFUSED stands for 'Connection Refused'. It indicates that Node.js attempted to establish a TCP connection to a specific port and IP address, but the target machine actively rejected the request. This occurs when there is no application listening on that port, or when system-level firewalls and network routing rules block socket requests.

Common Causes

• Target Service Offline: The database, cache, or external microservice is not running.
• Wrong Port Configuration: The code is querying the wrong port (e.g., hitting port 3000 instead of 8080).
• Docker Localhost Isolation: Querying 'localhost' inside a Docker container to hit a database running on the host machine.
• Firewall Blocking: Security groups, firewalls, or routing tables are dropping/refusing connection packages.

Common Mistakes

• Forgetting to start local datastores (Redis, Postgres, Mongo) before initiating development servers.
• Using localhost inside Docker containers instead of utilizing Docker networks.

How to Fix

Framework-Specific Examples

const mongoose = require('mongoose');

mongoose.connect('mongodb://localhost:27017/myapp')
  .then(() => {
    app.listen(3000, () => console.log('App running on port 3000'));
  })
  .catch(err => {
    if (err.code === 'ECONNREFUSED') {
      console.error('MongoDB is offline. Exiting process.');
      process.exit(1);
    }
  });

Server Configuration Examples

upstream app_servers {
    server 127.0.0.1:3000;
    server 127.0.0.1:3001 backup;
}

Best Practices

• Use environment variables for hostnames and ports.
• Implement server dependency health-check loops in deployment configurations.

Frequently Asked Questions (FAQ)