Service or dependency connection refused

What this failure means

A TCP connection attempt was actively refused by the target host. The service is either not running on that address and port, has not finished starting up, or is bound to a different interface.

Symptoms

Faultline looks for one or more of these log fragments:

connection refused
Connection refused
could not connect to server
connection was refused
ECONNREFUSED
ECONNRESET
connect: connection refused
no connection could be made

Diagnosis

A TCP connection attempt was actively refused by the target host. The service is either not running on that address and port, has not finished starting up, or is bound to a different interface.

Fix steps

1. Add a readiness probe before the connecting step:

   wait-for-it.sh <host>:<port> -t 30
   # or with curl retry:
   curl --retry 10 --retry-delay 3 --retry-connrefused http://<host>:<port>/health
   

2. Check whether the service container actually started successfully:

   docker compose logs <service>      # Docker Compose
   kubectl logs <pod>                 # Kubernetes
   

3. Confirm the port the service is listening on:

   ss -tlnp | grep <port>
   

4. For Docker Compose services: use the service name as the hostname (e.g., postgres, redis), not localhost — containers on a shared network resolve each other by service name.

5. Check for race conditions: the client may be starting before the server is ready. Add an explicit health-check dependency in the CI service definition.

Validation

• curl -sf http://<host>:<port>/health or nc -zv <host> <port> — confirm the service responds before re-running.
• Re-run the failing step and confirm no ECONNREFUSED error.

Why it matters

In CI, this typically means a test or build step tried to contact a service (database, cache, API) before the service was ready to accept connections. It can also mean the service container never started, or the wrong host/port is configured.

Prevention

• Use service health checks in Docker Compose or CI service definitions.
• Add explicit wait steps with a timeout and retry loop.
• Define service startup order in CI to avoid race conditions.
• Standardize service hostnames and ports in shared test helpers or env files so jobs do not guess connection targets.

How Faultline detects it

Use faultline explain connection-refused to see the full playbook.

faultline analyze build.log
faultline explain connection-refused

Generated from playbooks/bundled/log/network/connection-refused.yaml. Do not edit directly.