Redis "Connection refused" on 127.0.0.1:6379 in CI

By Kaveh Alemi·Latchkey

A Redis client could not connect to 127.0.0.1:6379. Redis is not listening there yet (service still starting) or the host/port is wrong. This is a connectivity problem and is frequently a transient readiness race.

What this error means

A test or migration step fails with "connect ECONNREFUSED 127.0.0.1:6379" (or a similar refused error from your Redis client). It commonly passes on retry once the Redis service container is up.

Error: connect ECONNREFUSED 127.0.0.1:6379
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1595:16)

Common causes

Redis service not ready

The Redis service container is still starting when the client connects, so the connection is refused. Transient.

Wrong host/port mapping

The port is not published on the runner, or the client points at the wrong host for the job type.

How to fix it

Add a Redis healthcheck and wait

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

Poll redis-cli ping before use

until redis-cli -h 127.0.0.1 -p 6379 ping | grep -q PONG; do sleep 1; done

How to prevent it

• Gate Redis usage on a redis-cli ping healthcheck.
• Publish the Redis port and use the matching host for the job.
• On managed runners (Latchkey), self-healing auto-retries transient failures such as Redis being briefly slow to accept connections.

Frequently asked questions

Related guides

References

• GitHub Actions documentation