Redis "Connection refused" before the container is ready in CI

The Redis container is launching but the server is not yet listening on 6379 when your step connects, so the connect is refused. A redis-cli ping healthcheck or wait loop closes the race.

What this error means

The first connection fails with "Could not connect to Redis at 127.0.0.1:6379: Connection refused", then succeeds on retry once the container is warm.

Could not connect to Redis at 127.0.0.1:6379: Connection refused

Common causes

The step connects before redis-server is listening

Redis starts fast, but on a busy runner there is still a brief window after the container exists where the port is not accepting connections.

No healthcheck gates the dependent steps

Without a redis-cli ping health command, GitHub Actions starts steps as soon as the container exists.

How to fix it

Add a redis-cli ping healthcheck

Hold steps until Redis answers PING with PONG.

services:
  redis:
    image: redis:7
    ports: ['6379:6379']
    options: >-
      --health-cmd "redis-cli ping"
      --health-interval 5s
      --health-timeout 3s
      --health-retries 10

Wait for PONG in a loop

For docker-compose, poll until PING returns PONG.

until [ "$(redis-cli -h 127.0.0.1 -p 6379 ping)" = "PONG" ]; do
  echo "waiting for redis"; sleep 1
done

How to prevent it

• Add a redis-cli ping healthcheck to the Redis service.
• Connect to the mapped 127.0.0.1:6379, not the container name, from steps.
• Use the PING/PONG check instead of a fixed sleep.

Related guides