CI "curl: (7) Failed to connect" - Connection Refused/Unreachable

curl exit code 7 is CURLE_COULDNT_CONNECT - DNS resolved, but the TCP connection could not be established. The port was refused, filtered, or the host was briefly unreachable.

What this error means

A curl call fails with curl: (7) Failed to connect to <host> port <n> ... Connection refused (or no route to host). Resolution worked, so it is not DNS - the connection itself did not establish. A retry often succeeds when the cause was transient.

curl: (7) Failed to connect to localhost port 8080 after 0 ms: Connection refused
# or
curl: (7) Failed to connect to mirror.example.com port 443: No route to host

Common causes

The service is not up yet (race)

A common CI pattern: a curl health-check runs before a service container or local server has finished starting, so the port is not listening yet and the connection is refused.

Transient unreachability or a closed port

A brief network drop, an overloaded upstream that stopped accepting connections, or a firewall change makes the host unreachable for that moment.

How to fix it

Wait for readiness before connecting

Poll the endpoint with a bounded loop so the check does not race service startup.

for i in $(seq 1 30); do
  curl -fsS http://localhost:8080/health && break
  sleep 2
done

Retry and verify reachability

1. For external hosts, retry with backoff - a transient blip usually clears.
2. Confirm the host/port is correct and actually listening (ss -ltn, nc -vz host port).
3. Pull from a mirror if one upstream is unreachable.

How to prevent it

• Gate health-checks behind a bounded readiness wait, not a single curl.
• Retry external connections with backoff.
• Use mirrors so one unreachable upstream is not fatal.

Related guides