◆Error Codes Wiki

Docker Compose Network Errors — Container Communication and DNS Resolution Failures

Warningdocker

Overview

Fix Docker Compose networking issues including containers unable to communicate, DNS resolution failures, and port binding conflicts between services.

Key Details

  • Docker Compose creates a default bridge network where services can reference each other by service name
  • Container DNS resolution uses Docker's built-in DNS server at 127.0.0.11
  • Services must be on the same Docker network to communicate by name
  • Port mapping (-p) exposes ports to the host; inter-container communication uses internal ports directly
  • Network conflicts occur when Docker's default subnet overlaps with the host network or VPN

Common Causes

  • Services on different Docker networks cannot resolve each other's names
  • Using 'localhost' instead of the service name to reference another container
  • Docker network subnet conflicting with host network, VPN, or corporate network ranges
  • Container started before its dependency is ready (no health check or depends_on)

Steps

  1. 1Use service names for inter-container communication: 'http://db:5432' not 'http://localhost:5432'
  2. 2Verify services are on the same network: 'docker network inspect [project]_default'
  3. 3Add health checks and depends_on with condition: service_healthy for startup ordering
  4. 4Fix subnet conflicts: add 'networks: default: driver: bridge ipam: config: - subnet: 172.28.0.0/16' to docker-compose.yml
  5. 5Debug DNS: 'docker exec [container] nslookup [service-name]' to test name resolution

Tags

docker-composenetworkdnscontainercommunication

Related Items

linux-kubernetes-pod-crashloopbackoff

More in Docker

linux-docker-common-errorsLinux Docker Common Errors — Container, Network & Volume Troubleshooting
Error
linux-docker-container-errors-detailedDocker Container Errors — Exit Codes, OOMKilled, and Networking Issues
Error
linux-container-permission-namespaceLinux Container Permission Errors — User Namespaces and Rootless Containers
Warning
linux-kubernetes-pod-crashloopbackoffKubernetes CrashLoopBackOff — Pod Restart Loop and Container Crash Debugging
Error
linux-kubernetes-pod-imagepullbackoffKubernetes ImagePullBackOff — Container Image Download and Registry Errors
Error

Frequently Asked Questions

In Docker, localhost refers to the container itself, not the host machine. Use the service name defined in docker-compose.yml to connect to other containers. Use 'host.docker.internal' to reach the host.