Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

A Flask or Sidekiq container cannot reach Redis on localhost:6379

ErrorError 99 connecting to localhost:6379. Cannot assign requested address.

Short answer

Inside a container, localhost is that container, not your Redis service. The client libraries default to localhost:6379, so the worker or web container looks for Redis in itself and finds nothing. Give each container the Redis service name as host, set it on every service that needs it, and use the container port.

  • Applies to Docker Engine 28, Docker Compose 2, redis-py 5 and newer, Sidekiq 7 and newer, Redis 7
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at the Redis address from inside the failing container, not from your host. If the variable is empty, or it names localhost or 127.0.0.1, you have the cause.

    docker compose exec web env | grep -i redis
    docker compose exec sidekiq env | grep -i redis
  2. 2Match what you see, then jump to its fix

    1. 1No Redis address appears in the container's environment, or the code builds the client without a hostThe client uses its default host, which is the container itselfFix
    2. 2Rails pages load, but the sidekiq container logs Error connecting to Redis on 127.0.0.1:6379Only the web service got REDIS_URL, the Sidekiq service did notFix
    3. 3Redis is mapped as 6380:6379 and the app connects to redis:6380, and the connection is refusedThe URL carries the published host port instead of the container portFix
    4. 4The service name does not resolve, or the connection is refused, only after you added custom networks to the compose fileThe two services do not share a networkFix

What does the error look like?

  • Error 99 connecting to localhost:6379. Cannot assign requested address.
  • Error connecting to Redis on 127.0.0.1:6379 (Errno::ECONNREFUSED)

Cause 1 of 4

The client uses its default host, which is the container itself

1Check

redis-py connects to host localhost and port 6379 unless you tell it otherwise. In a Compose project every service registers its own name with an internal DNS server, so the Redis container is reachable as redis (or whatever the service is called), not as localhost.

grep -rn "Redis(" app/ | head
docker compose exec web python -c "import socket; print(socket.gethostbyname('redis'))"

2Fix

Pass the service name through an environment variable and build the client from it.

# compose.yaml
services:
  redis:
    image: redis:7
  web:
    build: .
    environment:
      REDIS_URL: redis://redis:6379/0

# app.py
import os, redis
r = redis.Redis.from_url(os.environ["REDIS_URL"])

3Verify

Ping Redis from inside the web container.

docker compose exec web python -c "import os, redis; print(redis.Redis.from_url(os.environ['REDIS_URL']).ping())"

Confirmed by redis.readthedocs.io

Did this fix it?

Cause 2 of 4

Only the web service got REDIS_URL, the Sidekiq service did not

1Check

Sidekiq tries localhost:6379 by default and picks up REDIS_URL if it is set. Each service has its own environment, so a variable written under web does not exist in the sidekiq container. Compare what each service sees.

docker compose exec web printenv REDIS_URL
docker compose exec sidekiq printenv REDIS_URL

2Fix

Share one definition between the services, so no worker can be left without it.

x-redis-env: &redis-env
  REDIS_URL: redis://redis:6379/0

services:
  web:
    environment: *redis-env
  sidekiq:
    command: bundle exec sidekiq
    environment: *redis-env

3Verify

Restart the worker and read its log. It no longer names 127.0.0.1.

docker compose up -d --force-recreate sidekiq
docker compose logs sidekiq --tail 20

Confirmed by github.com

Did this fix it?

Cause 3 of 4

The URL carries the published host port instead of the container port

1Check

In a ports entry, the left number is the host port and the right one is the container port. Traffic between services uses the container port. The host port matters only for a client outside the Compose network, such as redis-cli on your laptop.

docker compose ps redis
docker compose config | grep -n -A3 "ports:"

2Fix

Inside the network, use redis:6379. Keep the mapped port for tools on your host only.

# inside the Compose network
REDIS_URL=redis://redis:6379/0

# from the host, with ports: ["6380:6379"]
redis-cli -p 6380 ping

3Verify

The app starts without the error, and the host tool answers on the mapped port.

docker compose logs web --tail 20

Confirmed by docs.docker.com

Did this fix it?

Cause 4 of 4

The two services do not share a network

1Check

Services reach each other by name only when they share a network. A service that joins just one custom network is isolated from services on another one.

docker compose config | grep -n -B1 -A4 "networks:"

2Fix

Attach Redis and every client to a network they have in common.

services:
  redis:
    image: redis:7
    networks: [backend]
  web:
    build: .
    networks: [backend]
networks:
  backend: {}

3Verify

The service name resolves from the client container.

docker compose exec web getent hosts redis

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Never write localhost or 127.0.0.1 in the config of a service that talks to another container; read the address from the environment.
  • Define shared settings once with a YAML anchor or an env_file so web, workers and schedulers all see the same Redis address.
  • Remember the two meanings of the port in a ports entry: containers talk to the right-hand number.
  • Add a Redis ping to the start-up of the app, so a wrong address fails the first minute, not at the first job.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.