Executing an API request, downloading a software repository script, or testing microservice connectivity using cURL in the Linux terminal only to receive the terminal output: “curl: (7) Failed to connect to [hostname/IP] port [port]: Connection refused” or “Network is unreachable” halts command-line operations immediately. In cURL, exit code 7 (CURLE_COULDNT_CONNECT) represents an inability to establish a complete TCP three-way handshake with the target destination. Unlike DNS errors (which trigger code 6), cURL successfully resolved the hostname into an IP address, but the subsequent TCP SYN packet was either actively rejected with a TCP RST (Reset) packet or dropped silently by an intervening firewall. This guide provides a systematic, step-by-step diagnostic workflow to isolate and resolve cURL error 7 across Linux distributions.
What Causes cURL Error 7 (CURLE_COULDNT_CONNECT)?
Establishing an outbound TCP socket requires seamless coordination across the network stack:
- Target Service Is Not Listening: The web server daemon (such as Nginx, Apache, or a Node.js API) is stopped or bound exclusively to a different network interface (e.g., bound to
127.0.0.1instead of0.0.0.0). - Firewall Filtering and Port Blocking: Local Linux firewalls (
ufw,firewalld,iptables) or cloud security groups (AWS, Azure, DigitalOcean) blocking incoming packets on the specified port. - Incorrect Port Specification: Requesting an HTTP endpoint on port 443 without SSL/TLS, or targeting port 80 when the web server operates on port 8080 or 3000.
- Outbound Network / Proxy Misconfiguration: System environment variables (
http_proxy,https_proxy) routing traffic to an unreachable proxy server. - Loopback Interface Routing Glitches: Attempting to reach localhost inside Docker containers or virtual machines without proper network bridging.
Method 1: Verify the Target Service Status and Listening Ports
If you are curling a service running on the local machine or a remote server you administer, verify that the daemon is actively listening for incoming TCP connections.
- Check if the web server daemon is active:
sudo systemctl status nginx # Or apache2, docker, etc. - If the service is stopped or failed, start it:
sudo systemctl start nginx - Inspect listening TCP sockets using the
ssutility:sudo ss -tulpn | grep -E ':(80|443|8080)' - Crucial Diagnostic: Look at the Local Address:Port column. If you see
127.0.0.1:8080, the service only accepts connections from the local host itself. To accept external network traffic, the configuration must bind to0.0.0.0:8080or[::]:8080.
Method 2: Inspect and Adjust Local Linux Firewalls
If the service is running but cURL fails from an external host, local Linux packet filters are likely dropping the traffic.
For UFW (Ubuntu / Debian):
- Check active firewall rules:
sudo ufw status verbose - If the target port is not allowed, open it (for example, port 443 for HTTPS or 8080 for web apps):
sudo ufw allow 443/tcp sudo ufw allow 8080/tcp sudo ufw reload
For firewalld (RHEL / CentOS / Fedora):
- Check active zone configuration:
sudo firewall-cmd --list-all - Allow the necessary port permanently:
sudo firewall-cmd --add-port=8080/tcp --permanent sudo firewall-cmd --reload
Method 3: Test Socket Reachability with Netcat or Telnet
Isolate whether the connection issue is specific to cURL or represents a broader transport-layer blockage using lightweight socket tools.
- Use nc (netcat) with zero-I/O mode (
-z) and verbose output (-v):nc -zv example.com 443 - If netcat outputs “Connection to example.com port 443 [tcp/https] succeeded!”, the TCP socket is open and cURL may be encountering protocol-specific issues (such as proxy or SSL negotiation).
- If netcat outputs “Connection refused” or hangs until timing out, the failure is definitively at the network/routing layer.
Method 4: Inspect and Unset Broken Environment Proxy Variables
Misconfigured system proxies intercept cURL commands and route them into non-existent endpoints.
- Check your current shell environment for active proxy configurations:
env | grep -i proxy - If you observe variables such as
http_proxy,https_proxy, orall_proxypointing to invalid addresses, temporarily unset them:unset http_proxy https_proxy all_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY - Alternatively, instruct cURL to bypass all system proxies explicitly using the
--noproxyflag:curl --noproxy '*' -I https://example.com
Method 5: Handle Docker Container and Localhost Routing
When curling a containerized service from within another container or the host, targeting localhost often routes to the container’s isolated loopback rather than the intended service.
- If curling from the host machine to a Docker container, ensure the container exposed and published its ports properly:
Verify thedocker psPORTScolumn shows0.0.0.0:8080->80/tcp. - If curling from inside a container to the host machine on Linux, use
172.17.0.1(default docker0 bridge gateway) or run the container with--add-host=host.docker.internal:host-gatewayrather than targetinglocalhost.
cURL Error 7 Troubleshooting Quick Guide
| Observed Message | Network Meaning | Immediate Action |
|---|---|---|
| Connection refused | Target sent TCP RST packet | Verify service is running and listening on port |
| Connection timed out | SYN packet dropped silently | Check firewall (UFW, firewalld, cloud security groups) |
| Network is unreachable | No routing entry to host | Check default gateway and routing table (ip route) |
| Proxy connection failed | Outdated proxy variable | Unset http_proxy or run curl –noproxy ‘*’ |
Following this structured diagnostic methodology ensures you quickly isolate whether a daemon state, firewall policy, or network interface configuration is causing cURL connection failures.