Python "redis.exceptions.ConnectionError" in CI

redis.exceptions.ConnectionError: Error connecting to Redis is raised when redis-py cannot open a socket to the configured host and port, typically because the Redis service container is not running or not yet accepting connections.

What this error means

A test fails with "redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused." early in setup.

redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused.

Common causes

The Redis service container is down or not ready

The job did not start a Redis service, or tests ran before it began accepting connections.

Wrong host in the CI network

localhost was used where Redis is reachable under a service hostname.

How to fix it

Start Redis as a service and wait for readiness

1. Declare a Redis service in the CI job and point the client at the right host.
2. Poll with PING until Redis answers before running dependent tests.
3. Use a fake/in-memory Redis in unit tests that do not need the real server.

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

How to prevent it

• Latchkey managed runners auto-retry transient connection failures while service containers warm up.
• Gate Redis-dependent tests on a PING readiness check.
• Use a fake Redis for pure unit tests.

Related guides