Connection Refused Error

What It Means

Connection refused means the TCP connection was actively rejected. The server received your connection request but responded with a RST (reset) packet, indicating nothing is listening on that port.

# Browser error
ERR_CONNECTION_REFUSED

# Node.js/curl error
Error: connect ECONNREFUSED 127.0.0.1:3000

# Python error
ConnectionRefusedError: [Errno 111] Connection refused

Connection Refused vs Timeout

Common Causes

• Service not running: The application hasn't started or crashed
• Wrong port: Connecting to the wrong port number
• Bound to localhost only: Service only listening on 127.0.0.1
• Firewall blocking: Local firewall rejecting connections
• Wrong IP address: Server moved to different IP
• Container not exposed: Docker port not mapped

Diagnosing the Issue

# Check if process is listening on the port
ss -tlnp | grep :3000
netstat -tlnp | grep :3000
lsof -i :3000

# Check if port is open
nc -zv localhost 3000
telnet localhost 3000

# Check from another machine
curl -v http://server-ip:3000

# Check service status
systemctl status nginx
systemctl status node-app
docker ps

# Check what the process is bound to
ss -tlnp | grep node
# 127.0.0.1:3000 = localhost only
# 0.0.0.0:3000   = all interfaces (accessible remotely)

Service Not Running

# Start the service
systemctl start nginx
systemctl start your-app

# Check logs if it won't start
journalctl -u nginx -n 50
journalctl -u your-app -n 50

# Start a Node.js app
node server.js &

# Or with PM2
pm2 start server.js
pm2 logs

Bound to Localhost Only

If your app binds to 127.0.0.1, it won't accept remote connections.

# Node.js - bind to all interfaces
app.listen(3000, '0.0.0.0', () => {
  console.log('Listening on all interfaces');
});

# Python Flask
app.run(host='0.0.0.0', port=5000)

# Django
python manage.py runserver 0.0.0.0:8000

# Nginx - check listen directive
listen 80;           # All interfaces
listen 127.0.0.1:80; # Localhost only

Docker Port Mapping

# Wrong - port not exposed
docker run myapp

# Correct - map host port to container port
docker run -p 3000:3000 myapp

# Check exposed ports
docker ps
docker port container_name

# docker-compose.yml
services:
  app:
    ports:
      - "3000:3000"

Firewall Rules

# UFW (Ubuntu)
sudo ufw status
sudo ufw allow 3000/tcp
sudo ufw reload

# iptables
sudo iptables -L INPUT -n --line-numbers
sudo iptables -A INPUT -p tcp --dport 3000 -j ACCEPT

# firewalld (RHEL/CentOS)
sudo firewall-cmd --list-all
sudo firewall-cmd --add-port=3000/tcp --permanent
sudo firewall-cmd --reload

# Windows
netsh advfirewall firewall show rule name=all

Quick Checklist

• Is the service running? systemctl status
• Is it listening on the right port? ss -tlnp
• Is it bound to 0.0.0.0 or just localhost?
• Is the firewall allowing the port?
• Are you connecting to the right IP/hostname?
• If Docker, is the port mapped?