When an app cannot reach its data service, the cause is almost always one of four things. Each has a distinct symptom.
| Symptom (app log) | Cause | Fix |
|---|---|---|
ECONNREFUSED 127.0.0.1:PORT | Address is localhost | Use the service's container name |
getaddrinfo ENOTFOUND NAME | Name does not resolve: wrong name, service container stopped, or no shared user-defined network | Fix the name, start it, or attach both to one network |
ECONNREFUSED 172.x.x.x:PORT | Name resolves, nothing listens on that port: wrong port, or the service binds 127.0.0.1 | Fix the port, bind 0.0.0.0 |
| Connection timed out | Address belongs to no running container (a stale IP) | Use names, not IPs |
Work through it in order
text
1. What failed? docker ps -a exited? restarting?
2. Why? docker logs APP read the error above
3. Which networks? docker inspect APP / DB compare network names
4. Who shares a network? docker network inspect NET Containers section
5. Test from inside docker run --rm --network NET alpine:3.20 nslookup DB
6. Fix and recreate docker rm, docker run keep names, volumes
7. Verify curl, docker logs, docker psCompare the networks
sh
docker inspect --format '{{json .NetworkSettings.Networks}}' redisPrints one key per attached network ({"bridge":{…}}). With several containers, ask the network instead:
sh
docker network inspect --format '{{range .Containers}}{{.Name}} {{end}}' counter-netAn empty line means nothing running is attached.
Test the path from a throwaway container
A short-lived Alpine container on the same network tests DNS and the port without touching the app:
sh
docker run --rm --network counter-net alpine:3.20 nslookup redis
docker run --rm --network counter-net redis:7.4 redis-cli -h redis PINGtext
PONGWhat can change in place, and what cannot
| Change | Command | Recreate? |
|---|---|---|
| Add a network | docker network connect NET C | no |
| Remove a network | docker network disconnect NET C | no |
Environment variables (REDIS_HOST) | docker rm, docker run -e … | yes |
Published ports (-p) | docker rm, docker run without -p | yes |
| Data in a named volume | Mount the same volume in the new container | data survives |
Before you remove a data container, check where its data lives:
sh
docker inspect --format '{{json .Mounts}}' redisIf Type is volume with a name, a new container that mounts that name keeps the data. Without a volume, the data is gone with the container.