Redis connection refused or service unavailable

What this failure means

The application or test suite could not connect to Redis. The service is not running, has not finished starting, or the connection string points to the wrong host or port.

Symptoms

Faultline looks for one or more of these log fragments:

Redis::CannotConnectError
redis.exceptions.ConnectionError
JedisConnectionException: Could not connect to Redis
Could not connect to Redis at
Error 111 connecting to
ECONNREFUSED 127.0.0.1:6379
ECONNREFUSED ::1:6379
[ioredis] Unhandled error event

Diagnosis

Redis connection failures in CI occur when:

• The Redis service container has not finished starting before the application attempts its first connection.
• The hostname is wrong — for example, localhost instead of the service name (redis, cache) in a Docker Compose or GitHub Actions services block.
• The default Redis port 6379 is misconfigured or blocked.
• The Redis server requires a password (AUTH) and the client is not providing one, or providing an incorrect one.

Client libraries surface this differently:

• Python (redis-py): redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused.
• Ruby: Redis::CannotConnectError: Error connecting to Redis on localhost:6379 (Errno::ECONNREFUSED)
• Node.js (ioredis / node-redis): Error: connect ECONNREFUSED 127.0.0.1:6379
• Java (Jedis): JedisConnectionException: Could not connect to Redis at 127.0.0.1:6379: Connection refused.

Fix steps

1. Verify Redis is running and accepting connections:

   redis-cli -h 127.0.0.1 -p 6379 ping
   # Expected response: PONG
   

2. Add a healthcheck to the Redis service in your CI configuration:

   GitHub Actions example:

   services:
     redis:
       image: redis:7
       options: >-
         --health-cmd "redis-cli ping"
         --health-interval=10s
         --health-retries=5
   

3. For Docker Compose, depend on the healthcheck:

   services:
     redis:
       image: redis:7
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 5s
         retries: 5
     app:
       depends_on:
         redis:
           condition: service_healthy
   

4. If Redis requires a password, set REDIS_PASSWORD and configure the client accordingly. A missing AUTH produces NOAUTH Authentication required, not a connection refused — if that is the error, check credentials instead.

5. Check the hostname used by the client. In GitHub Actions, the Redis service is accessible at 127.0.0.1, not redis, because it is port-mapped to the host:

   echo "REDIS_URL=$REDIS_URL"
   redis-cli -h 127.0.0.1 ping
   

Validation

• redis-cli -h <host> -p 6379 ping returns PONG.
• Re-run the failing test step and confirm no connection error appears.

Why it matters

Redis is widely used in CI test setups for caching, session storage, and job queuing. A startup race condition causes all cache-dependent tests to fail with a connection refused error. The fix — a Redis healthcheck — is simple but easy to forget when first adding Redis to a CI pipeline.

Prevention

• Include a healthcheck in every Redis service definition. redis-cli ping is the minimal probe and always available in the official Redis image.
• If your app checks Redis availability at startup, add a startup wait (redis-cli ping loop) as a fallback before the main process runs.

Try it locally

redis-cli -h 127.0.0.1 -p 6379 ping
redis-cli -h 127.0.0.1 -p 6379 ping

How Faultline detects it

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

faultline analyze build.log
faultline explain redis-connection-refused

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