ECONNREFUSED — Connection Refused Error Explained

ECONNREFUSED (errno 111)

ECONNREFUSED occurs when a client attempts to connect to a host:port combination where nothing is listening. The operating system actively refuses the TCP connection with a RST packet.

Common Scenarios

1. Service not running:

# Check if the service is listening
ss -tlnp | grep :3000
lsof -i :3000

2. Docker networking issues:

# Wrong: connecting to localhost from inside a container
# Containers have their own network namespace
# Use the service name instead:
DATABASE_URL=postgres://user:pass@db:5432/mydb

3. Binding to wrong interface:

// Wrong: only accessible from localhost
server.listen(3000, '127.0.0.1');

// Right: accessible from any interface
server.listen(3000, '0.0.0.0');

4. Firewall blocking:

# Check iptables rules
sudo iptables -L -n | grep 3000

# Check ufw status
sudo ufw status

ECONNREFUSED vs ETIMEDOUT vs EHOSTUNREACH

Error	Meaning	Typical Cause
ECONNREFUSED	RST received	Service not running on that port
ETIMEDOUT	No response	Firewall silently dropping packets
EHOSTUNREACH	ICMP unreachable	No route to host, host down

Debugging Checklist

1. Is the service process running? (ps aux | grep service)
2. Is it listening on the expected port? (ss -tlnp)
3. Is it bound to the right interface? (0.0.0.0 vs 127.0.0.1)
4. Are you using the correct hostname/IP?
5. Is a firewall blocking the connection?
6. (Docker) Are you using service names instead of localhost?