# Docker Compose Network Error: Troubleshooting Service Connectivity

Your Docker Compose services can't communicate. One service can't reach another, DNS resolution fails, or the network itself doesn't get created properly. Network errors in Docker Compose can prevent your entire application stack from functioning, even when each service individually runs fine.

Common error messages:

bash
ERROR: Service 'web' failed to build: failed to connect to 'db' service

Container logs show:

bash
Host 'db' not found
Connection refused to host 'db' port 5432

Or network creation fails:

bash
ERROR: failed to create network: network name already exists

Understanding Docker Compose Networking

Default Network Behavior

When you run docker-compose up, Docker Compose:

  1. 1.Creates a default bridge network named <project>_default
  2. 2.Connects all services to this network
  3. 3.Each service can reach others by service name as hostname
yaml
# Simple compose with default networking
services:
  web:
    image: nginx
  db:
    image: postgres
# web can reach db at hostname 'db'

Custom Networks

You can define custom networks:

```yaml services: web: networks: - frontend db: networks: - backend api: networks: - frontend - backend

networks: frontend: backend: ```

Quick Diagnosis

Check Network Status

```bash # List networks docker network ls

# Find compose networks docker network ls | grep <project_name> ```

Inspect Network

bash
docker network inspect <project>_default

Check Service Connectivity

bash
# From one service to another
docker-compose exec web ping db
docker-compose exec web nslookup db

Check DNS Resolution

bash
docker-compose exec web cat /etc/resolv.conf
docker-compose exec web getent hosts db

Common Causes and Fixes

Cause 1: Service Name DNS Resolution Fails

Services can't resolve each other's hostnames.

Symptoms: `` web_1 | Host 'db' not found web_1 | DNS lookup failed for 'db'

Diagnosis:

bash
docker-compose exec web nslookup db
docker-compose exec web ping db -c 3

Fix 1: Ensure services are on same network

```yaml services: web: networks: - appnet db: networks: - appnet

networks: appnet: ```

Fix 2: Check network exists

bash
docker network inspect <project>_default

If network is missing:

bash
docker-compose down
docker-compose up --force-recreate

Fix 3: Use container_name explicitly

yaml
services:
  db:
    container_name: database
    image: postgres
  web:
    environment:
      - DB_HOST=database

Fix 4: Use links (legacy, but works)

yaml
services:
  web:
    links:
      - db:database

Cause 2: Services Start Before Dependencies

A service tries to connect to another that hasn't started yet.

Symptoms: `` web_1 | Connection refused: db:5432 web_1 | ECONNREFUSED 172.18.0.2:5432

Fix 1: Use depends_on

yaml
services:
  web:
    depends_on:
      - db
  db:
    image: postgres

Note: depends_on only ensures order of startup, not that the service is ready.

Fix 2: Use healthcheck with depends_on

yaml
services:
  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
  web:
    depends_on:
      db:
        condition: service_healthy

Fix 3: Add startup delay in application

```python # In your application code import time import psycopg2

for i in range(10): try: conn = psycopg2.connect(host='db', port=5432) break except: time.sleep(5) ```

Fix 4: Use wait-for-it script

yaml
services:
  web:
    image: myapp
    command: ["./wait-for-it.sh", "db:5432", "--", "npm", "start"]
    depends_on:
      - db

Create wait-for-it.sh:

```bash #!/bin/bash host=$1 shift cmd=$@

until nc -z $host; do echo "Waiting for $host..." sleep 2 done

exec $cmd ```

Cause 3: Network Creation Fails

Docker Compose can't create the network.

Symptoms: `` ERROR: failed to create network custom_network: network name already exists

Diagnosis:

bash
docker network ls | grep custom_network
docker network inspect custom_network

Fix 1: Remove conflicting network

bash
docker network rm custom_network
docker-compose up

Fix 2: Use unique network name

yaml
networks:
  myapp_custom:
    name: myapp_custom_unique

Fix 3: Let Docker Compose manage

bash
# Remove all compose artifacts
docker-compose down --volumes --remove-orphans
docker-compose up

Cause 4: Port Conflicts Within Network

Services trying to use same internal ports.

Symptoms: `` ERROR: port is already allocated

Fix 1: Use different exposed ports

yaml
services:
  web1:
    ports:
      - "8001:80"
  web2:
    ports:
      - "8002:80"

Fix 2: Don't expose ports for internal communication

yaml
services:
  web:
    # No ports exposed - only reachable from other services
    expose:
      - "8080"
  proxy:
    ports:
      - "80:80"

Cause 5: External Network Issues

Can't connect to pre-defined external network.

Symptoms: `` ERROR: network external_net not found

Fix 1: Create external network first

bash
docker network create external_net
docker-compose up

Fix 2: Use correct external network declaration

yaml
networks:
  external_net:
    external: true
    name: external_net

Fix 3: Check network driver compatibility

bash
docker network inspect external_net --format '{{.Driver}}'
# Must be compatible with compose (bridge, overlay)

Cause 6: IPv6 or MTU Issues

Network configuration mismatches.

Symptoms: - Large requests fail - DNS works but data transfer fails - Intermittent connection drops

Fix: Configure MTU

yaml
networks:
  appnet:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: 1400

Fix: Disable IPv6 if causing issues

json
// /etc/docker/daemon.json
{
  "ipv6": false
}

Cause 7: Firewall Blocking Internal Traffic

Firewall blocks Docker internal network traffic.

Symptoms: `` Connection timed out No route to host

Diagnosis:

bash
sudo iptables -L -n -v | grep DROP
sudo ufw status

Fix: Allow Docker networks

```bash # For UFW sudo ufw allow from 172.16.0.0/12 sudo ufw allow from 192.168.0.0/16

# Or modify UFW before.rules sudo nano /etc/ufw/before.rules # Add: -A POSTROUTING -s 172.18.0.0/16 ! -o br+ -j MASQUERADE ```

Cause 8: Service Using Host Network

A service configured with host network can't use service discovery.

Symptoms: - Service can't resolve other service names - Only localhost connections work

Fix: Use bridge network for service discovery

yaml
services:
  web:
    # Change from:
    # network_mode: host
    # To:
    networks:
      - appnet
    ports:
      - "80:80"

Network Configuration Patterns

Pattern 1: Frontend/Backend Separation

```yaml services: nginx: networks: - frontend ports: - "80:80"

api: networks: - frontend - backend

db: networks: - backend # No ports exposed - only reachable by api

networks: frontend: backend: ```

Pattern 2: Shared Network with Multiple Compose Files

```yaml # docker-compose.yml services: web: networks: - shared

networks: shared: external: true name: shared_net ```

bash
docker network create shared_net
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

Pattern 3: Network Aliases

yaml
services:
  db:
    networks:
      appnet:
        aliases:
          - database
          - postgres

Now services can reach db as db, database, or postgres.

Verification Steps

  1. 1.Check network connectivity:
  2. 2.```bash
  3. 3.docker-compose exec web ping db
  4. 4.docker-compose exec web nc -zv db 5432
  5. 5.`
  6. 6.Check DNS resolution:
  7. 7.```bash
  8. 8.docker-compose exec web getent hosts db
  9. 9.docker-compose exec web nslookup db
  10. 10.`
  11. 11.Check network exists:
  12. 12.```bash
  13. 13.docker network inspect <project>_default
  14. 14.`
  15. 15.Verify all services connected:
  16. 16.```bash
  17. 17.docker network inspect <project>_default --format '{{range .Containers}}{{.Name}}{{println}}{{end}}'
  18. 18.`
  19. 19.Test full stack:
  20. 20.```bash
  21. 21.docker-compose up
  22. 22.docker-compose ps
  23. 23.docker-compose exec web curl http://api:8080/health
  24. 24.`

Docker Compose network errors usually stem from configuration issues—services on different networks, startup order problems, or firewall interference. Check that services share a network, use proper healthchecks, and allow Docker's internal traffic through firewalls.