Docker Errors Compose

docker-errors-compose

Quick Reference

First Response: Validate the Compose File

ALWAYS run docker compose config before debugging any Compose error. This command parses, resolves variables, and renders the final configuration. If it fails, the Compose file itself is broken.

# Validate and render resolved config
docker compose config

# Validate without output (exit code only)
docker compose config -q

# Show resolved environment variables
docker compose config --environment

Critical Warnings

NEVER ignore docker compose config validation errors — they indicate structural problems that ALWAYS cause runtime failures.

NEVER use depends_on without condition: service_healthy when the dependent service needs initialization time (databases, message brokers). The default service_started condition only waits for the container to start, NOT for the application to be ready.

NEVER use the deprecated version: field — it is ignored by Compose v2 and generates warnings.

ALWAYS use named volumes for persistent data. Anonymous volumes are lost on docker compose down.

ALWAYS quote port mappings that start with numbers below 60 to prevent YAML parsing as sexagesimal (base-60) numbers.

---

Diagnostic Decision Tree

Compose File Won't Parse

docker compose config fails
├── YAML syntax error?
│   ├── Check indentation (spaces only, NEVER tabs)
│   ├── Check colons have space after them in mappings
│   └── Check strings with special chars are quoted
├── "services" missing?
│   └── The `services` key is REQUIRED — add it
├── Unknown attribute error?
│   ├── Check spelling of Compose directives
│   └── Check indentation level (attribute under wrong parent)
└── Variable interpolation error?
    ├── Unset variable? → Use ${VAR:-default} or set in .env
    ├── Dollar sign in value? → Escape with $$ (e.g., $$HOME)
    └── Single-quoted in .env? → Values are literal, no interpolation

Services Won't Start

docker compose up fails
├── Port conflict?
│   ├── "port is already allocated" → Find process: lsof -i :PORT
│   └── Two services using same host port → Change one
├── Dependency failure?
│   ├── "dependency failed to start" → Check dependent service logs
│   ├── Healthcheck timeout → Increase interval/retries/start_period
│   └── service_completed_successfully never exits 0 → Fix init service
├── Build failure?
│   ├── "build path ... does not exist" → Check context path
│   ├── Dockerfile not found → Check dockerfile path relative to context
│   └── Build context too large → Add .dockerignore
├── Image not found?
│   ├── "pull access denied" → docker login or check image name
│   └── "manifest unknown" → Verify tag exists in registry
├── Volume mount error?
│   ├── "permission denied" → Match UID/GID or fix ownership
│   ├── Named volume not declared → Add to top-level volumes:
│   └── External volume missing → Create it first
└── Environment variable error?
    ├── "variable is not set" → Define in .env or environment
    └── Wrong value resolved → Check precedence order

Orphan Container Warnings

"Found orphan containers"
├── Service removed from compose.yaml → docker compose down --remove-orphans
├── Project name changed → Use consistent -p flag or COMPOSE_PROJECT_NAME
└── Suppress warning → Set COMPOSE_IGNORE_ORPHANS=true

---

Error Diagnostic Table

---

Common Patterns

Proper Service Dependencies with Healthcheck

services:
  app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy

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

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

Safe Port Mapping

ports:
  # ALWAYS quote port mappings to prevent YAML parsing issues
  - "8080:80"
  # Bind to localhost for development
  - "127.0.0.1:5432:5432"

Environment Variable with Required Check

environment:
  DATABASE_URL: ${DATABASE_URL:?DATABASE_URL must be set}
  LOG_LEVEL: ${LOG_LEVEL:-info}

Validation Workflow

# Step 1: Validate syntax and variable resolution
docker compose config -q

# Step 2: Start with build and force recreation
docker compose up --build --force-recreate -d

# Step 3: Check service status
docker compose ps

# Step 4: Check logs for failing services
docker compose logs --tail 50 <service-name>

---

Profile Dependency Resolution

When a profiled service depends on another profiled service, both profiles must be active or the dependency must have no profile:

services:
  app:
    image: myapp

  debug-tools:
    image: debug:latest
    profiles: [debug]
    depends_on:
      - app           # OK: app has no profile, always available

  test-runner:
    image: test:latest
    profiles: [test]
    depends_on:
      - debug-tools   # FAILS unless debug profile is also active

Fix: Either activate both profiles (--profile test --profile debug), remove the cross-profile dependency, or remove the profile from the dependency.

---

Reference Links

• references/diagnostics.md -- Complete error message to cause to solution mapping
• references/examples.md -- Common Compose error scenarios with step-by-step fixes
• references/anti-patterns.md -- Compose configuration mistakes and corrections

Official Sources

• https://docs.docker.com/compose/compose-file/
• https://docs.docker.com/compose/compose-file/05-services/
• https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/
• https://docs.docker.com/compose/how-tos/profiles/
• https://docs.docker.com/reference/cli/docker/compose/

Docker Compose Anti-Patterns

AP-01: Using depends_on Without Healthchecks

What happens: App starts before the database is ready, causing connection errors and crash loops.

# WRONG
services:
  app:
    depends_on:
      - db
  db:
    image: postgres:16

# CORRECT
services:
  app:
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

Rule: ALWAYS use condition: service_healthy with a healthcheck for services that need initialization time (databases, message brokers, caches).

---

AP-02: Using the Deprecated version Field

What happens: Compose v2 ignores it and emits a warning. Developers waste time picking version numbers.

# WRONG
version: "3.8"
services:
  web:
    image: nginx

# CORRECT
services:
  web:
    image: nginx

Rule: NEVER include version: in Compose files. The Compose Specification is the only format since Compose v2.

---

AP-03: Anonymous Volumes for Persistent Data

What happens: Data is lost when running docker compose down because anonymous volumes are not preserved.

# WRONG — anonymous volume
services:
  db:
    image: postgres:16
    volumes:
      - /var/lib/postgresql/data

# CORRECT — named volume
services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Rule: ALWAYS use named volumes for any data that must survive container recreation.

---

AP-04: Hardcoding Secrets in Compose Files

What happens: Secrets committed to version control. Anyone with repo access sees credentials.

# WRONG
services:
  db:
    environment:
      POSTGRES_PASSWORD: "super-secret-password"

# CORRECT — interpolation from .env (add .env to .gitignore)
services:
  db:
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}

# BEST — use Docker secrets
services:
  db:
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

Rule: NEVER hardcode passwords or API keys in Compose files. Use .env files (gitignored) or Docker secrets.

---

AP-05: Exposing Ports to All Interfaces

What happens: Services are accessible from any network interface, including public networks.

# WRONG — accessible from any interface
ports:
  - "5432:5432"

# CORRECT — bound to localhost only
ports:
  - "127.0.0.1:5432:5432"

Rule: ALWAYS bind development ports to 127.0.0.1 unless external access is explicitly required. Database ports (5432, 3306, 27017, 6379) should NEVER be exposed to all interfaces.

---

AP-06: Using container_name with Scalable Services

What happens: docker compose up --scale web=3 fails because container names must be unique.

# WRONG — prevents scaling
services:
  web:
    image: nginx
    container_name: my-nginx

# CORRECT — let Compose manage names
services:
  web:
    image: nginx

Rule: NEVER use container_name on services you might need to scale. Compose generates unique names automatically.

---

AP-07: Unquoted Port Mappings

What happens: YAML interprets numbers containing colons as sexagesimal (base-60) values. 56:56 becomes 3396.

# WRONG — potential YAML parsing surprise
ports:
  - 56:56
  - 80:80

# CORRECT — always quote
ports:
  - "56:56"
  - "80:80"

Rule: ALWAYS quote port mappings in Compose files to prevent YAML sexagesimal interpretation.

---

AP-08: restart: always Without Resource Limits

What happens: A crashing service restarts infinitely, consuming CPU and memory without bound.

# WRONG — crash loop with no limits
services:
  app:
    image: myapp
    restart: always

# CORRECT — restart with safety limits
services:
  app:
    image: myapp
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 512M

Rule: ALWAYS combine restart: policies with resource limits via deploy.resources.limits to prevent runaway containers.

---

AP-09: Not Using Profiles for Optional Services

What happens: Debug tools, admin panels, and test utilities run in all environments, wasting resources and expanding the attack surface.

# WRONG — debug tools always running
services:
  app:
    image: myapp
  phpmyadmin:
    image: phpmyadmin
  mailhog:
    image: mailhog/mailhog

# CORRECT — optional services behind profiles
services:
  app:
    image: myapp
  phpmyadmin:
    image: phpmyadmin
    profiles: [debug]
  mailhog:
    image: mailhog/mailhog
    profiles: [debug]

# Start with debug tools only when needed
docker compose --profile debug up -d

Rule: ALWAYS assign profiles to services that are not needed in production (debug tools, admin panels, test services).

---

AP-10: Large Build Context Without .dockerignore

What happens: Docker sends the entire project directory (including node_modules, .git, data files) as build context. Builds are slow and may include sensitive files in the image.

# WRONG — no .dockerignore, sending everything
services:
  app:
    build: .

Fix: Create .dockerignore in the build context:

node_modules
.git
.env
*.log
data/
dist/
coverage/

Rule: ALWAYS create a .dockerignore file when using build: in Compose. At minimum, exclude .git/, node_modules/, and any data directories.

---

AP-11: Using Default Bridge Network

What happens: Services cannot resolve each other by name. DNS resolution only works on user-defined networks.

# WRONG — relying on default bridge (implicit)
services:
  app:
    image: myapp
    network_mode: bridge
  db:
    image: postgres
    network_mode: bridge

# CORRECT — Compose creates a default user-defined network automatically
# Simply do not specify network_mode at all
services:
  app:
    image: myapp
  db:
    image: postgres

Rule: NEVER set network_mode: bridge explicitly. Compose automatically creates a user-defined bridge network with DNS resolution enabled.

---

AP-12: Missing Named Volume Declaration

What happens: docker compose config fails with "refers to undefined volume".

# WRONG — volume used but not declared
services:
  db:
    volumes:
      - pgdata:/var/lib/postgresql/data

# CORRECT — volume declared at top level
services:
  db:
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Rule: ALWAYS declare named volumes in the top-level volumes: section. This is a Compose requirement, not optional.

---

AP-13: Ignoring docker compose config Output

What happens: Developers debug runtime issues that are caused by misconfigured Compose files. Hours spent on symptoms rather than root cause.

# WRONG workflow — jump straight to up and debug
docker compose up -d
docker compose logs
# ... head scratching ...

# CORRECT workflow — validate first
docker compose config -q          # Quick validation
docker compose config             # Inspect resolved output
docker compose up -d              # Start with confidence

Rule: ALWAYS run docker compose config before docker compose up when troubleshooting. This catches YAML errors, undefined variables, missing volumes/networks, and merge issues before they become runtime failures.

---

AP-14: Cross-Profile Dependencies

What happens: Service A (profile: test) depends on Service B (profile: debug). Starting only the test profile leaves Service B inactive, causing dependency failure.

# WRONG — cross-profile dependency
services:
  debug-db:
    profiles: [debug]
  test-runner:
    profiles: [test]
    depends_on:
      - debug-db    # Not started unless debug profile is active

# CORRECT — shared profile or no profile on dependency
services:
  debug-db:
    profiles: [debug, test]    # Available in both profiles
  test-runner:
    profiles: [test]
    depends_on:
      - debug-db

Rule: NEVER create depends_on chains across different profiles unless you ALWAYS activate all required profiles together. Dependencies must share at least one profile with their dependents, or have no profile assignment.

Docker Compose Error Diagnostics — Complete Reference

YAML & File Parsing Errors

Service Definition Errors

Port & Network Errors

Volume & Storage Errors

Environment Variable Errors

Build Errors

Dependency & Lifecycle Errors

Profile Errors

Compose Config Validation Errors

Diagnostic Commands Reference

Docker Compose Error Scenarios — Examples with Fixes

Scenario 1: Database Not Ready When App Starts

Symptom

Application crashes on startup with "connection refused" to database, even though depends_on is set.

Broken Configuration

services:
  app:
    image: myapp:latest
    depends_on:
      - db
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/mydb

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: pass
      POSTGRES_USER: user
      POSTGRES_DB: mydb

Why It Fails

depends_on with default behavior (service_started) only waits for the container to start. PostgreSQL needs 5-15 seconds to initialize before accepting connections.

Fixed Configuration

services:
  app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/mydb

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: pass
      POSTGRES_USER: user
      POSTGRES_DB: mydb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

---

Scenario 2: Port Conflict Between Services

Symptom

Error response from daemon: driver failed programming external connectivity
on endpoint project-web-1: Bind for 0.0.0.0:8080 failed: port is already allocated

Broken Configuration

services:
  web:
    image: nginx
    ports:
      - "8080:80"

  api:
    image: myapi
    ports:
      - "8080:3000"    # Duplicate host port!

Fix

services:
  web:
    image: nginx
    ports:
      - "8080:80"

  api:
    image: myapi
    ports:
      - "8081:3000"    # Different host port

External Port Conflict Fix

If the port is used by a process outside Docker:

# Find what's using the port
lsof -i :8080
# or
ss -tlnp | grep 8080

# Stop the conflicting process, then retry
docker compose up -d

---

Scenario 3: Environment Variable Not Set

Symptom

WARNING: The DATABASE_PASSWORD variable is not set. Defaulting to a blank string.

Or with strict syntax:

variable "DATABASE_PASSWORD" is not set and is required

Broken Configuration

services:
  app:
    image: myapp
    environment:
      DATABASE_PASSWORD: ${DATABASE_PASSWORD}

Fix Option A: Create .env file

# Create .env in same directory as compose.yaml
echo "DATABASE_PASSWORD=my-secure-password" > .env

Fix Option B: Use default value

environment:
  DATABASE_PASSWORD: ${DATABASE_PASSWORD:-default-dev-password}

Fix Option C: Require with error message

environment:
  DATABASE_PASSWORD: ${DATABASE_PASSWORD:?DATABASE_PASSWORD must be set in .env or environment}

Verify Resolution

docker compose config --environment

---

Scenario 4: Orphan Container Warning

Symptom

WARN[0000] Found orphan containers ([project-old-service-1]) for this project.
Use 'docker compose down --remove-orphans' to clean them up.

Cause

A service was removed from compose.yaml but its container still exists from a previous run.

Fix

# Remove orphan containers
docker compose down --remove-orphans

# Or suppress the warning permanently
export COMPOSE_IGNORE_ORPHANS=true

---

Scenario 5: Volume Permission Denied

Symptom

Application log shows:

Error: EACCES: permission denied, open '/data/app.db'

Broken Configuration

services:
  app:
    image: myapp    # Runs as UID 1000
    volumes:
      - ./data:/data    # Host dir owned by root

Fix Option A: Match UID in Dockerfile

FROM node:20-alpine
RUN mkdir -p /data && chown -R node:node /data
USER node

Fix Option B: Set user in Compose

services:
  app:
    image: myapp
    user: "${UID:-1000}:${GID:-1000}"
    volumes:
      - ./data:/data

Fix Option C: Fix host directory ownership

sudo chown -R 1000:1000 ./data

---

Scenario 6: Build Context Not Found

Symptom

failed to solve: failed to read dockerfile: open Dockerfile: no such file or directory

Broken Configuration

services:
  app:
    build:
      context: ./backend
      dockerfile: docker/Dockerfile    # Relative to context!

Project Structure

project/
  compose.yaml
  backend/
    docker/
      Dockerfile
    src/

Why It Fails

dockerfile path is relative to context, so Compose looks for ./backend/docker/Dockerfile. If the file is actually at ./docker/Dockerfile (relative to project root), it will not be found.

Fixed Configuration

services:
  app:
    build:
      context: ./backend
      dockerfile: docker/Dockerfile    # Must exist at ./backend/docker/Dockerfile

Or if Dockerfile is at project root level:

services:
  app:
    build:
      context: .
      dockerfile: docker/Dockerfile    # Now relative to project root

---

Scenario 7: YAML Sexagesimal Port Parsing

Symptom

Port mapping produces unexpected numbers. Port 56:56 gets interpreted as 3396.

Broken Configuration

ports:
  - 56:56      # YAML parses as sexagesimal (base-60): 5*60+6 = 306

Fix

ports:
  - "56:56"    # ALWAYS quote port mappings

Rule: ALWAYS quote port mappings in Compose files to prevent YAML base-60 interpretation.

---

Scenario 8: Dollar Sign in Environment Value

Symptom

invalid interpolation format for services.app.environment.PASSWORD

Broken Configuration

services:
  app:
    environment:
      PASSWORD: pa$$word    # Compose tries to interpolate $$

Fix

services:
  app:
    environment:
      PASSWORD: "pa$$$$word"    # $$ produces literal $

Or use env_file with format: raw (Compose 2.30.0+):

services:
  app:
    env_file:
      - path: ./secrets.env
        format: raw    # No interpolation

---

Scenario 9: Profile Dependency Not Starting

Symptom

docker compose --profile test up
# test-runner starts but debug-tools does not

Broken Configuration

services:
  debug-tools:
    image: debug:latest
    profiles: [debug]

  test-runner:
    image: test:latest
    profiles: [test]
    depends_on:
      - debug-tools    # debug profile not active!

Fix Option A: Activate both profiles

docker compose --profile test --profile debug up

Fix Option B: Remove profile from dependency

services:
  debug-tools:
    image: debug:latest
    # No profile — always available

  test-runner:
    image: test:latest
    profiles: [test]
    depends_on:
      - debug-tools

Fix Option C: Share the same profile

services:
  debug-tools:
    image: debug:latest
    profiles: [test, debug]    # Active in both profiles

  test-runner:
    image: test:latest
    profiles: [test]
    depends_on:
      - debug-tools

---

Scenario 10: Named Volume Not Declared

Symptom

service "db" refers to undefined volume db-data: invalid compose project

Broken Configuration

services:
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data
# Missing top-level volumes declaration!

Fix

services:
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:    # ALWAYS declare named volumes at top level

---

Scenario 11: External Network Does Not Exist

Symptom

network myshared declared as external, but could not be found

Configuration

services:
  app:
    networks:
      - myshared

networks:
  myshared:
    external: true

Fix

# Create the external network first
docker network create myshared

# Then start Compose
docker compose up -d

---

Scenario 12: Compose Override File Confusion

Symptom

Services have unexpected configuration. Port mappings or environment variables do not match what is in compose.yaml.

Cause

Compose automatically loads compose.override.yaml if it exists alongside compose.yaml. This is silent and can cause unexpected merging.

Diagnosis

# See the fully merged and resolved config
docker compose config

# Check which files are being loaded
docker compose config --resolve-image-digests 2>&1 | head -5

Fix

Remove or rename compose.override.yaml if it is not intentional. Or explicitly control which files are loaded:

docker compose -f compose.yaml up -d    # Only base file, no override