Connection refused (ECONNREFUSED)
ID: networking/connection-refused
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| any | active | — | — | — |
Root Cause
The target host actively refused the TCP connection. This means the host is reachable but no service is listening on the requested port. The OS sends a TCP RST packet in response to the SYN.
genericWorkarounds
-
93% success Start or restart the target service on the correct port
1. Verify the service status: systemctl status your-service 2. Check if something is listening on the expected port: ss -tlnp | grep :PORT 3. Start the service: systemctl start your-service 4. Check logs for startup failures: journalctl -u your-service --no-pager -n 50 5. Verify it is now listening: ss -tlnp | grep :PORT 6. Test connection: nc -zv host PORT
-
88% success Verify the correct host and port configuration on the client
1. Confirm the expected host:port from documentation or configuration 2. Verify DNS resolution: dig hostname +short 3. Check if the service listens on a different port: ss -tlnp on the server 4. Check if the service binds to 127.0.0.1 vs 0.0.0.0: ss -tlnp | grep :PORT 5. If bound to localhost only, reconfigure to bind to 0.0.0.0 or the correct interface 6. Check firewall rules are not redirecting traffic: iptables -t nat -L
Dead Ends
Common approaches that don't work:
-
Increase connection timeout hoping the service will eventually start listening
95% fail
Connection refused is an immediate, active rejection (RST packet), not a timeout. The OS immediately tells the client that nothing is listening. Increasing timeout has no effect because the error occurs instantly, not after a delay.
-
Change the client to use a different network interface or source IP
90% fail
ECONNREFUSED means the target host received the SYN packet and responded with RST because no process is listening on that port. The issue is on the server side, not the network path. Changing source IP or interface does not affect what is listening on the server.