redis-cli "Error 111 connecting to localhost:6379. Connection refused" in CI
redis-cli reached the socket for localhost:6379 and the kernel returned ECONNREFUSED (errno 111): nothing is listening yet. In CI this almost always means the Redis service container started but has not finished booting, or the port was never mapped into the job.
What this error means
A step that runs redis-cli or connects to Redis fails immediately with "Could not connect to Redis at localhost:6379: Connection refused" or "Error 111 connecting to localhost:6379. Connection refused" while the service container is still starting.
Could not connect to Redis at localhost:6379: Connection refused
Error 111 connecting to localhost:6379. Connection refused.Common causes
The job connected before Redis was ready
The service container is created but redis-server has not yet printed "Ready to accept connections", so the port refuses connections for the first second or two.
The port is not mapped or the host is wrong
On a job that runs on the runner host, the service port must be published with ports:; if it is not, localhost:6379 has no listener.
How to fix it
Wait for Redis to be ready before connecting
- Add a health check to the service so the job waits until Redis answers.
- Or poll with redis-cli ping in a loop before the first real command.
- Only start your tests once PING returns PONG.
services:
redis:
image: redis:7
ports: ['6379:6379']
options: >-
--health-cmd "redis-cli ping"
--health-interval 5s
--health-timeout 3s
--health-retries 10Poll for readiness in the step
If you cannot use service health checks, block until PING succeeds before running tests.
for i in $(seq 1 30); do
redis-cli -h localhost -p 6379 ping && break
echo "waiting for redis..."; sleep 1
doneHow to prevent it
- Always gate tests behind a Redis health check or PING loop.
- Publish the service port with
ports:when the job runs on the runner host. - Do not assume a freshly created service accepts connections instantly.