Docker Errors Networking

docker-errors-networking

Quick Reference

Rule #1: ALWAYS Use User-Defined Networks

NEVER use the default bridge network. It lacks DNS resolution, proper isolation, and configuration flexibility. ALWAYS create a user-defined bridge network:

docker network create mynet
docker run --network mynet --name web nginx
docker run --network mynet --name api node
# api can reach web via hostname "web" — automatic DNS

Network Debugging Flowchart

Container cannot communicate
        |
        v
[Are containers on the SAME network?]
  |                    |
  NO                   YES
  |                    |
  v                    v
docker network     [Can they ping by IP?]
connect mynet        |              |
container            NO             YES
  |                  |              |
  v                  v              v
Retry            [Check firewall/  [DNS issue — check
                  iptables]        container name and
                  See §Firewall    /etc/resolv.conf]
                                   See §DNS
        |
        v
[Can container reach internet?]
  |              |
  NO             YES
  |              |
  v              v
Check ip_forward Port mapping issue
and DNS config   See §Port Mapping
See §No Internet

---

Diagnostic Table: Symptom > Cause > Fix

DNS Resolution Failures

Connection Refused

Port Mapping Issues

Default Bridge Limitations

No Internet from Container

Firewall and iptables Conflicts

Overlay Network Issues

Subnet Conflicts

---

Network Debugging Commands

Essential Diagnostic Commands

# Check which network a container is on
docker inspect --format='{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}' <ctr>

# Get container IP address
docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <ctr>

# List all containers on a network
docker network inspect --format='{{range .Containers}}{{.Name}} {{end}}' mynet

# Check DNS resolution inside container
docker exec <ctr> nslookup <target-hostname>
docker exec <ctr> cat /etc/resolv.conf

# Test connectivity between containers
docker exec <ctr> ping -c 2 <target-hostname>
docker exec <ctr> wget -qO- http://<target-hostname>:<port>/

# Check listening ports inside container
docker exec <ctr> ss -tlnp
docker exec <ctr> netstat -tlnp

# Check published port mapping
docker port <ctr>

# Inspect full network configuration
docker network inspect mynet

# Check iptables rules (host)
sudo iptables -L -n -v
sudo iptables -t nat -L -n -v

# Check IP forwarding (host)
sysctl net.ipv4.ip_forward

Compose-Specific Debugging

# Check default network created by Compose
docker network ls --filter "label=com.docker.compose.project=<project>"

# Verify service DNS names
docker compose exec <service> nslookup <other-service>

# Check Compose network config
docker compose config | grep -A 10 networks

---

Compose Networking Patterns

Correct: Services on Shared Network

# docker-compose.yml
services:
  web:
    image: nginx
    ports:
      - "8080:80"  # Only needed for external access
    networks:
      - app-net

  api:
    image: node:20-alpine
    networks:
      - app-net  # Can reach "web" by hostname

networks:
  app-net:
    driver: bridge

Correct: Isolated Backend Network

services:
  web:
    networks:
      - frontend
      - backend

  api:
    networks:
      - backend

  db:
    networks:
      - backend  # Not accessible from frontend

networks:
  frontend:
  backend:
    internal: true  # No external internet access

Anti-Pattern: Missing Network Declaration

# NEVER rely on the default Compose network for multi-project setups
# ALWAYS declare explicit networks when services need cross-project communication
services:
  api:
    networks:
      - shared-net

networks:
  shared-net:
    external: true  # Must exist before compose up

---

Critical Rules

ALWAYS use user-defined bridge networks -- the default bridge lacks DNS, isolation, and live connect/disconnect.

ALWAYS bind services to 0.0.0.0 inside containers -- binding to 127.0.0.1 makes the service unreachable from other containers.

ALWAYS restart Docker after firewall changes -- firewall reloads flush Docker's iptables chains.

NEVER hardcode container IP addresses -- IPs change on restart. Use DNS names or network aliases.

NEVER use --link -- it is legacy and deprecated. Use user-defined networks with DNS.

NEVER expose ports with -p for container-to-container communication -- containers on the same network can reach all ports directly.

---

Reference Links

• references/diagnostics.md -- Complete error-to-cause-to-solution lookup table
• references/examples.md -- Network debugging sessions with step-by-step resolution
• references/anti-patterns.md -- Networking configuration mistakes and why they fail

Official Sources

• https://docs.docker.com/engine/network/
• https://docs.docker.com/engine/network/drivers/bridge/
• https://docs.docker.com/engine/network/drivers/overlay/
• https://docs.docker.com/engine/daemon/troubleshoot/

Networking Anti-Patterns — What NOT to Do

Common Docker networking configuration mistakes, why they fail, and the correct alternative.

Docker Engine 24+, Docker Compose v2.

---

AP-001: Using the Default Bridge Network

The Mistake

# Relying on the default bridge for container communication
docker run -d --name redis redis
docker run -d --name webapp myapp
# webapp tries to connect to "redis" by hostname — FAILS

Why It Fails

The default bridge network does NOT provide embedded DNS resolution. Containers can only reach each other by IP address, which changes on restart. The legacy --link flag provides name resolution but is deprecated and not maintained.

The Correct Way

# ALWAYS create and use a user-defined bridge network
docker network create app-net
docker run -d --name redis --network app-net redis
docker run -d --name webapp --network app-net myapp
# webapp can now reach "redis" by hostname via Docker's embedded DNS

---

AP-002: Hardcoding Container IP Addresses

The Mistake

# Application config
DATABASE_HOST = "172.18.0.3"  # Hardcoded container IP
REDIS_HOST = "172.18.0.4"

Why It Fails

Container IP addresses are assigned dynamically and change every time a container is recreated, restarted, or moved to a different network. Hardcoded IPs break silently when infrastructure changes.

The Correct Way

# ALWAYS use container names or network aliases
DATABASE_HOST = "db"      # Docker DNS resolves this
REDIS_HOST = "redis"      # Docker DNS resolves this

# Or use network aliases for more descriptive names
docker run --network app-net --network-alias database postgres

---

AP-003: Binding Services to 127.0.0.1 Inside Containers

The Mistake

// Node.js server inside container
app.listen(3000, '127.0.0.1');  // Only accessible from inside this container

# Flask inside container
app.run(host='127.0.0.1', port=5000)  # Only accessible from inside this container

Why It Fails

127.0.0.1 (localhost) inside a container refers to the container's own loopback interface. Other containers — even on the same Docker network — cannot reach this address. It is container-private.

The Correct Way

// ALWAYS bind to 0.0.0.0 inside containers
app.listen(3000, '0.0.0.0');  // Accessible from all network interfaces

# ALWAYS bind to 0.0.0.0 inside containers
app.run(host='0.0.0.0', port=5000)

---

AP-004: Using --link for Container Communication

The Mistake

docker run -d --name redis redis
docker run -d --name webapp --link redis:redis myapp

Why It Fails

--link is legacy and deprecated. It only works on the default bridge, does not support user-defined networks, cannot be updated without container recreation, and creates fragile coupling between containers.

The Correct Way

docker network create app-net
docker run -d --name redis --network app-net redis
docker run -d --name webapp --network app-net myapp
# DNS-based discovery — no --link needed

---

AP-005: Publishing Ports for Container-to-Container Communication

The Mistake

# docker-compose.yml
services:
  api:
    image: myapi
    ports:
      - "3000:3000"  # Published to host — unnecessary for inter-service traffic

  web:
    image: myweb
    environment:
      API_URL: "http://localhost:3000"  # Tries to reach via host — fragile

Why It Fails

Port publishing (-p / ports:) maps a container port to a host port. This is only needed for access from outside the Docker network. Containers on the same network can reach ALL ports of other containers directly — no publishing needed. Using localhost from one container does NOT reach another container.

The Correct Way

services:
  api:
    image: myapi
    # NO ports: needed for inter-service communication
    # Only add ports: if external access is required

  web:
    image: myweb
    ports:
      - "8080:80"  # Only web needs external access
    environment:
      API_URL: "http://api:3000"  # Use service name, not localhost

---

AP-006: Using depends_on Without Health Checks

The Mistake

services:
  db:
    image: postgres:16
    # No healthcheck defined

  webapp:
    depends_on:
      - db  # Only waits for container START, not service READY

Why It Fails

depends_on without condition: service_healthy only ensures the database container has started. PostgreSQL may take several seconds to initialize. The webapp connects immediately and gets connection refused because the database is not accepting connections yet.

The Correct Way

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s

  webapp:
    depends_on:
      db:
        condition: service_healthy  # Waits for health check to pass

---

AP-007: Ignoring Network Isolation Between Compose Projects

The Mistake

# Project A
cd frontend && docker compose up -d

# Project B
cd backend && docker compose up -d

# Expecting frontend to reach backend by service name — FAILS

Why It Fails

Each Compose project creates its own isolated default network (frontend_default, backend_default). Services in different projects cannot see each other because they are on separate networks with separate DNS scopes.

The Correct Way

# Create shared network first
docker network create shared-services

# Both projects reference the external network
networks:
  shared:
    external: true
    name: shared-services

services:
  myservice:
    networks:
      - default  # Keep internal communication
      - shared   # Add cross-project access

---

AP-008: Not Configuring Docker Address Pools with VPN

The Mistake

# Install Docker with default settings on a machine with corporate VPN
# Docker creates networks in 172.17-28.x.x and 192.168.x.x ranges
# VPN routes to 172.16.0.0/12 stop working

Why It Fails

Docker's default address pools (172.17.0.0/16 through 172.28.0.0/14, 192.168.0.0/16) overlap with many corporate VPN ranges. Docker's local routes take precedence, breaking VPN connectivity to those subnets.

The Correct Way

// /etc/docker/daemon.json — configure BEFORE creating any networks
{
  "default-address-pools": [
    {
      "base": "10.99.0.0/16",
      "size": 24
    }
  ]
}

sudo systemctl restart docker
# All new networks will use 10.99.x.x — no VPN conflict

---

AP-009: Forgetting to Restart Docker After Firewall Changes

The Mistake

# Reload firewall rules
sudo firewall-cmd --reload
# or: sudo ufw reload
# or: sudo iptables -F

# All Docker containers lose network connectivity
# Admin does not restart Docker

Why It Fails

Docker creates iptables chains (DOCKER, DOCKER-ISOLATION, DOCKER-USER) and NAT MASQUERADE rules at startup. When the firewall flushes iptables, these chains are destroyed. Without them, Docker cannot route traffic between containers or to the internet.

The Correct Way

# ALWAYS restart Docker after any firewall change
sudo firewall-cmd --reload && sudo systemctl restart docker

# Or automate with systemd:
# /etc/systemd/system/firewalld.service.d/docker.conf
[Service]
ExecStartPost=/usr/bin/systemctl restart docker

---

AP-010: Using host.docker.internal in Production

The Mistake

services:
  webapp:
    environment:
      DB_HOST: "host.docker.internal"  # Relies on Docker Desktop feature

Why It Fails

host.docker.internal is a Docker Desktop convenience feature. It does NOT work reliably on Linux Docker Engine in production. It is not a standard DNS name and its behavior varies across platforms and Docker versions.

The Correct Way

# For container-to-container: use Docker service names
services:
  webapp:
    environment:
      DB_HOST: "db"  # Another container on the same network

# For container-to-host on Linux:
# Use the host gateway IP or --network host
services:
  webapp:
    extra_hosts:
      - "host.docker.internal:host-gateway"  # Explicit and portable

---

AP-011: Exposing Database Ports to the Host

The Mistake

services:
  db:
    image: postgres:16
    ports:
      - "5432:5432"  # Database accessible from entire network

Why It Fails

Publishing the database port to the host makes it accessible from any machine that can reach the host. This is a security risk — databases should only be accessible from application containers, not from the network.

The Correct Way

services:
  db:
    image: postgres:16
    # NO ports: — only accessible from containers on the same network
    networks:
      - backend

  webapp:
    image: myapp
    networks:
      - backend
    environment:
      DB_HOST: db  # Reaches database via internal network

networks:
  backend:
    internal: true  # Optional: also blocks internet access from db

# If you need temporary host access for debugging:
# Use a one-off port-forward instead of permanent publishing
docker exec -it db psql -U postgres

---

AP-012: Not Using internal Networks for Backend Services

The Mistake

services:
  web:
    networks:
      - app-net
  db:
    networks:
      - app-net  # Database has full internet access — unnecessary risk

Why It Fails

By default, all Docker bridge networks allow outbound internet access. A compromised database container could exfiltrate data or download malware. Backend services (databases, caches, message queues) rarely need internet access.

The Correct Way

services:
  web:
    networks:
      - frontend
      - backend

  db:
    networks:
      - backend  # Cannot reach internet

networks:
  frontend:
    # Normal network — internet access allowed
  backend:
    internal: true  # No outbound internet — maximum isolation

---

Summary Table

Network Error Diagnostics — Complete Reference

Full error-to-cause-to-solution lookup table for Docker networking issues.

Docker Engine 24+, Docker Compose v2.

---

DNS Resolution Errors

---

Connection Refused Errors

---

Port Mapping Errors

---

Firewall and iptables Errors

---

Internet Connectivity Errors

---

Overlay Network Errors

---

Subnet Conflict Errors

---

Docker Compose Networking Errors

---

Diagnostic Command Reference

Quick Diagnosis Checklist

# 1. Are containers on the same network?
docker inspect --format='{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}' <ctr1>
docker inspect --format='{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}' <ctr2>

# 2. Can they resolve each other?
docker exec <ctr1> nslookup <ctr2-name>

# 3. Can they ping each other?
docker exec <ctr1> ping -c 2 <ctr2-name>

# 4. Is the service listening?
docker exec <target> ss -tlnp

# 5. What does the DNS config look like?
docker exec <ctr> cat /etc/resolv.conf

# 6. What is the full network config?
docker network inspect <network-name>

# 7. What ports are published?
docker port <ctr>

# 8. Is IP forwarding on?
sysctl net.ipv4.ip_forward

# 9. Are Docker iptables chains present?
sudo iptables -L DOCKER -n -v 2>/dev/null || echo "No DOCKER chain"

# 10. Docker daemon logs
journalctl -u docker --no-pager -n 50

Network Debugging Sessions — Worked Examples

Step-by-step debugging sessions showing how to diagnose and resolve Docker networking issues.

Docker Engine 24+, Docker Compose v2.

---

Session 1: Containers Cannot Communicate by Name

Scenario

Two containers started with docker run. Web app tries to connect to redis:6379 but gets dial tcp: lookup redis: no such host.

Diagnosis

# Step 1: Check what network each container is on
docker inspect --format='{{range $k, $v := .NetworkSettings.Networks}}{{$k}}{{end}}' webapp
# Output: bridge

docker inspect --format='{{range $k, $v := .NetworkSettings.Networks}}{{$k}}{{end}}' redis
# Output: bridge

# Step 2: Both on "bridge" (default) — this is the problem
# Default bridge does NOT provide DNS resolution

# Step 3: Verify DNS is broken
docker exec webapp nslookup redis
# Output: ** server can't find redis: NXDOMAIN

Fix

# Create user-defined network
docker network create app-net

# Stop and recreate containers on the new network
docker stop webapp redis
docker rm webapp redis

docker run -d --name redis --network app-net redis:7-alpine
docker run -d --name webapp --network app-net -p 8080:8080 mywebapp

# Verify DNS works
docker exec webapp nslookup redis
# Output: Name: redis  Address: 172.20.0.2

docker exec webapp ping -c 1 redis
# Output: PING redis (172.20.0.2): 56 data bytes — 64 bytes from 172.20.0.2

Key Lesson

ALWAYS use user-defined networks. The default bridge is legacy and lacks DNS resolution between containers.

---

Session 2: Port Already Allocated

Scenario

Starting a container with -p 3000:3000 fails with Error: port is already allocated.

Diagnosis

# Step 1: Find what is using port 3000
# On Linux:
sudo lsof -i :3000
# Output: node  12345  user  TCP *:3000 (LISTEN)

# Or:
sudo ss -tlnp | grep 3000
# Output: LISTEN  0  128  *:3000  *:*  users:(("node",pid=12345,fd=19))

# Step 2: It's a local Node.js dev server using the same port

Fix

# Option A: Stop the conflicting process
kill 12345

# Option B: Use a different host port
docker run -d -p 3001:3000 --name myapp myimage
# Access via localhost:3001, container still listens on 3000

# Option C: Check for orphaned Docker containers
docker ps -a --filter "publish=3000"
# If found, remove: docker rm -f <container-id>

Key Lesson

ALWAYS check for port conflicts before starting containers. Use lsof or ss to identify the blocking process.

---

Session 3: Service Binds to 127.0.0.1 Inside Container

Scenario

Container A can ping Container B by name, but curl http://api:8080 returns connection refused.

Diagnosis

# Step 1: Verify DNS works
docker exec web nslookup api
# Output: Name: api  Address: 172.20.0.3  — DNS is fine

# Step 2: Verify ping works
docker exec web ping -c 1 api
# Output: 64 bytes from 172.20.0.3 — Network layer is fine

# Step 3: Check what the target service is listening on
docker exec api ss -tlnp
# Output: LISTEN  0  128  127.0.0.1:8080  *:*  — PROBLEM FOUND
# The service binds to 127.0.0.1, only reachable from inside its own container

# Step 4: Verify from inside the target container
docker exec api curl -s http://127.0.0.1:8080
# Output: OK — works locally but not from other containers

Fix

# Change application config to bind to 0.0.0.0:8080

# For Node.js:
# app.listen(8080, '0.0.0.0')

# For Python Flask:
# app.run(host='0.0.0.0', port=8080)

# For Go:
# http.ListenAndServe(":8080", handler)  — empty host = all interfaces

# After fix:
docker exec api ss -tlnp
# Output: LISTEN  0  128  0.0.0.0:8080  *:*  — correct

docker exec web curl -s http://api:8080
# Output: OK

Key Lesson

ALWAYS bind to 0.0.0.0 inside containers. Binding to 127.0.0.1 makes the service unreachable from any other container, even on the same network.

---

Session 4: Docker Breaks VPN Connectivity

Scenario

After installing Docker, VPN connections to 10.0.0.0/8 range stop working. Some corporate hosts become unreachable.

Diagnosis

# Step 1: Check Docker network subnets
docker network ls
docker network inspect bridge --format='{{range .IPAM.Config}}{{.Subnet}}{{end}}'
# Output: 172.17.0.0/16

# Step 2: Check other Docker networks
docker network inspect $(docker network ls -q) --format='{{.Name}}: {{range .IPAM.Config}}{{.Subnet}}{{end}}'
# Output:
# bridge: 172.17.0.0/16
# mynet1: 172.18.0.0/16
# mynet2: 172.19.0.0/16

# Step 3: Check routing table
ip route | grep 172
# Docker routes override VPN routes for overlapping ranges

# Step 4: Check if Docker's default pool conflicts
# Default pools: 172.17.0.0/16 through 172.28.0.0/14, 192.168.0.0/16
# If VPN uses any 172.x.x.x or 192.168.x.x — conflict

Fix

# Configure Docker to use non-conflicting address pools
# Edit /etc/docker/daemon.json:
{
  "default-address-pools": [
    {
      "base": "10.99.0.0/16",
      "size": 24
    }
  ]
}

# Restart Docker
sudo systemctl restart docker

# Remove old networks and recreate
docker network prune -f
docker network create mynet
docker network inspect mynet --format='{{range .IPAM.Config}}{{.Subnet}}{{end}}'
# Output: 10.99.0.0/24 — no longer conflicts

Key Lesson

ALWAYS configure custom address pools when Docker runs alongside VPNs or in environments with specific network requirements. The default pools (172.17-28.x.x, 192.168.x.x) conflict with many corporate networks.

---

Session 5: Containers Lose Network After Firewall Reload

Scenario

After running firewall-cmd --reload (or ufw reload), all Docker containers lose internet connectivity.

Diagnosis

# Step 1: Test connectivity
docker exec webapp ping -c 1 8.8.8.8
# Output: ping: sendto: Operation not permitted

# Step 2: Check Docker iptables chains
sudo iptables -L DOCKER -n
# Output: Chain DOCKER (0 references)  — chain exists but no references

sudo iptables -L FORWARD -n
# Output: FORWARD chain shows DROP default, no Docker rules

# Step 3: The firewall reload flushed all iptables rules including Docker's NAT and filter chains

Fix

# Restart Docker to regenerate all iptables rules
sudo systemctl restart docker

# Verify rules are back
sudo iptables -L DOCKER -n -v
# Output: Chain DOCKER with forwarding rules

sudo iptables -t nat -L POSTROUTING -n
# Output: MASQUERADE rule for Docker subnet

# Test connectivity
docker exec webapp ping -c 1 8.8.8.8
# Output: 64 bytes from 8.8.8.8

Prevention

# Create a systemd override to restart Docker after firewall reload
# For firewalld:
sudo mkdir -p /etc/systemd/system/firewalld.service.d
cat <<'EOF' | sudo tee /etc/systemd/system/firewalld.service.d/docker.conf
[Service]
ExecStartPost=/usr/bin/systemctl restart docker
EOF
sudo systemctl daemon-reload

Key Lesson

ALWAYS restart Docker after any firewall changes. Firewall reloads flush iptables rules, destroying Docker's network configuration. Automate this with systemd dependencies.

---

Session 6: Compose Cross-Project Communication

Scenario

Two Compose projects need to communicate. Project A (frontend) needs to reach Project B's (backend) API service, but nslookup api fails.

Diagnosis

# Step 1: Check networks created by each project
docker network ls --filter "label=com.docker.compose.project=frontend"
# Output: frontend_default

docker network ls --filter "label=com.docker.compose.project=backend"
# Output: backend_default

# Step 2: Each project has its own isolated network — they cannot see each other
docker network inspect frontend_default --format='{{range .Containers}}{{.Name}} {{end}}'
# Output: frontend-web-1

docker network inspect backend_default --format='{{range .Containers}}{{.Name}} {{end}}'
# Output: backend-api-1 backend-db-1

Fix

# Step 1: Create a shared external network
docker network create shared-services

# Step 2: Update frontend docker-compose.yml

# frontend/docker-compose.yml
services:
  web:
    image: nginx
    networks:
      - default
      - shared

networks:
  shared:
    external: true
    name: shared-services

# backend/docker-compose.yml
services:
  api:
    image: node:20-alpine
    networks:
      - default
      - shared

  db:
    image: postgres:16
    networks:
      - default  # NOT on shared network — stays isolated

networks:
  shared:
    external: true
    name: shared-services

# Step 3: Restart both projects
docker compose -f backend/docker-compose.yml up -d
docker compose -f frontend/docker-compose.yml up -d

# Step 4: Verify cross-project DNS
docker compose -f frontend/docker-compose.yml exec web nslookup api
# Output: Name: api  Address: 10.99.1.3

Key Lesson

Compose projects are network-isolated by default. For cross-project communication, ALWAYS create a shared external network and add only the services that need to communicate.

---

Session 7: Container Cannot Reach the Internet

Scenario

A freshly installed Docker host. Containers can ping each other but cannot reach external hosts.

Diagnosis

# Step 1: Test external connectivity
docker run --rm alpine ping -c 1 8.8.8.8
# Output: PING 8.8.8.8: sendto: Network is unreachable

# Step 2: Check IP forwarding
sysctl net.ipv4.ip_forward
# Output: net.ipv4.ip_forward = 0  — DISABLED

# Step 3: Check NAT rules
sudo iptables -t nat -L POSTROUTING -n
# Output: (empty or no MASQUERADE rule)

Fix

# Step 1: Enable IP forwarding
sudo sysctl -w net.ipv4.ip_forward=1

# Step 2: Make persistent
echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf

# Step 3: Restart Docker to create NAT rules
sudo systemctl restart docker

# Step 4: Verify
docker run --rm alpine ping -c 1 8.8.8.8
# Output: 64 bytes from 8.8.8.8

sudo iptables -t nat -L POSTROUTING -n
# Output: MASQUERADE  all  --  172.17.0.0/16  !172.17.0.0/16

Key Lesson

Docker requires net.ipv4.ip_forward=1 for containers to reach the internet via NAT. ALWAYS verify this setting on fresh installations.

---

Session 8: Health Check with Networking Dependency

Scenario

Web application connects to database on startup. Compose starts both, but web crashes because database is not ready.

Diagnosis

docker compose up
# webapp exits with: connection refused to db:5432
# Database is still initializing

Fix

# docker-compose.yml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s

  webapp:
    image: mywebapp
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: "postgres://postgres:secret@db:5432/app"

docker compose up -d
# webapp waits until db health check passes before starting

# Verify health
docker compose ps
# NAME    STATUS
# db      running (healthy)
# webapp  running

Key Lesson

ALWAYS use health checks with `condition: service_healthy` for service dependencies. The depends_on without condition only waits for the container to start, NOT for the service to be ready.