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?

How to Monitor for Connection Refused Errors

Connection refused means your service is down. UptimeSignal detects connection refused errors immediately and alerts you when services stop accepting connections. Monitor all critical ports: 80 (HTTP), 443 (HTTPS), 22 (SSH), 5432 (PostgreSQL), 6379 (Redis).

Frequently Asked Questions