A Flask or Sidekiq container cannot reach Redis on localhost:6379
Error 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.
Fix it fast
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 redis2Match what you see, then jump to its fix
- 1
No 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
Rails 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
Redis 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
The 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
- 1
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
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_URL2Fix
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-env3Verify
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 20Confirmed by github.com
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 ping3Verify
The app starts without the error, and the host tool answers on the mapped port.
docker compose logs web --tail 20Confirmed by docs.docker.com
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 redisConfirmed by docs.docker.com
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
Back end
Node.js cannot reach Redis: ECONNREFUSED on port 6379
Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED
ECONNREFUSED on 6379 means no Redis server accepted the connection at the address the client used.
4 causes, each with a fixDatabases
Spring Boot cannot connect to Redis and shows the wrong host
org.springframework.data.redis.RedisConnectionFailureException: Unable to connect to Redis
Spring Boot connects to localhost:6379 unless it finds Redis properties it knows.
2 causes, each with a fixDatabases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
Node.js in Docker Compose cannot find mysql2/promise
The app works on the host but fails after docker compose up
mysql2/promise is a path inside the mysql2 package.
2 causes, each with a fixDatabases
A container cannot resolve the name of its database container
php_network_getaddresses: getaddrinfo failed
127.0.0.11 is Docker's own DNS server for custom networks.
3 causes, each with a fixDatabases
EF Core says 'transient failure' when it cannot reach PostgreSQL in Docker
The query fails only after a delay, because the connection is retried several times
The transient failure message comes from EF Core's retry layer, which hides the underlying connection error.
3 causes, each with a fix