How to fix 'ERROR: for Cannot start service …' in Compose

What this error means

Docker Compose reports:

ERROR: for <service> Cannot start service <service>: <reason>

Compose tried to create and start the container, but Docker Engine or the runtime failed. The key is the trailing reason (port bind, mount error, pull denied, runtime, etc.). Use targeted checks to resolve it quickly.

Quickstart: fast triage

1. Re-run in foreground to see the full error

• docker compose up <service> (without -d) shows the precise engine error.
• Also read docker compose logs -f <service>.

1. Inspect the failed container (if created)

• docker ps -a | grep <service>
• docker inspect <container_id> | less

1. Validate your Compose file

• docker compose config (catches invalid env/paths).

1. Try a clean recreate of the single service

• docker compose up -d --no-deps --force-recreate --build <service>

1. If it still fails, match the message to a cause below.

Minimal working example

Use this to confirm Docker and Compose are healthy on your machine.

docker-compose.yml:

version: "3.9"
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

Commands:

# Start
docker compose up -d

# Test
curl -sS http://localhost:8080/ | head -n 5

# Tear down
docker compose down

If this works, your engine and networking are fine; the issue is likely in your project’s config or environment.

Common causes and practical fixes

• Port already in use

  • Symptom: Bind for 0.0.0.0:80 failed: port is already allocated
  • Fix:
    • Find and stop the process or container using the port:
      • lsof -i :80 or netstat -tulpn | grep :80 (Linux)
      • docker ps --filter publish=80
      • docker stop <container>
    • Or change the host port in ports: "8080:80".

• External connectivity/iptables error

  • Symptom: driver failed programming external connectivity
  • Fix:
    • Remove orphan containers that still hold ports:
      • docker compose down --remove-orphans
    • Prune dangling networks and containers:
      • docker network prune -f; docker container prune -f
    • Check host firewall rules that block Docker’s NAT (nftables/iptables).

• Image not found / pull access denied

  • Symptom: pull access denied for <image>, repository does not exist or may require 'docker login'
  • Fix:
    • Check the image name and tag (avoid latest). Example: image: postgres:16-alpine
    • If private: docker login and ensure credentials are correct.
    • If built locally, ensure build: context: . and image tags match references.

• Build failed, container has no image to run

  • Symptom: Cannot start service ...: no such image
  • Fix:
    • docker compose build --no-cache <service>
    • Inspect Dockerfile logs for errors.

• Volume mount problems

  • Symptom: invalid mount config; Mounts denied; permission denied
  • Fix:
    • Use absolute host paths for bind mounts.
    • Ensure the host path exists before starting:
      • mkdir -p ./data && chmod -R 0777 ./data (or proper owner)
    • On Linux with SELinux, add :z or :Z to the volume: ./data:/var/lib/app:z
    • On Windows, prefer ${PWD} for paths: - "${PWD}/data:/data"
    • Avoid mounting over critical container dirs (e.g., /usr).

• External network not found

  • Symptom: network "mynet" declared as external, but could not be found
  • Fix:
    • docker network create mynet
    • Or remove external: true to let Compose create it.

• Runtime (OCI) errors

  • Symptom: OCI runtime create failed: ...
  • Fix:
    • Check platform compatibility: image built for linux/arm64 vs host arch.
      • Use: docker compose up --build --force-recreate --pull always
      • Or set: platform: linux/amd64 (when appropriate)
    • Verify cgroup configuration and Docker Engine health: docker info

• No space left on device

  • Symptom: failed to create shim task: ... no space left on device
  • Fix:
    • docker system df; docker system prune -af --volumes
    • Free host disk on /var/lib/docker and mountpoint disks used by volumes.

• Environment/config errors

  • Symptom: variable not set; invalid reference format
  • Fix:
    • Ensure required env vars exist: export DB_USER=... or .env file
    • Validate: docker compose config

• Startup order/service dependency

  • Symptom: app fails immediately because DB/cache not ready
  • Fix:
    • Add healthchecks and depends_on with condition: service_healthy.
    • Example:

services:
  db:
    image: postgres:16-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 10
  api:
    build: ./api
    depends_on:
      db:
        condition: service_healthy

Step-by-step diagnostic flow

1. Get the exact error

• docker compose up <service> (no -d) to see the full message.

1. Check container state

• docker ps -a shows Exited/Dead/Created states.
• docker logs <container> if it started and exited quickly.

1. Verify ports and mounts

• Ports: ss -tulpn | grep :<host_port>
• Mounts: ensure host paths exist and permissions are correct.

1. Networks

• docker network ls; docker network inspect <network>

1. Images

• docker images | grep <image>
• Rebuild or pull: docker compose build <service> || docker compose pull <service>

1. Clean up and retry

• docker compose down --remove-orphans
• docker volume prune -f (if safe), docker network prune -f
• docker compose up -d <service>

Pitfalls to avoid

• Using latest tags: pin explicit, tested versions.
• Reusing project names unintentionally: use -p <name> to isolate stacks.
• Relative bind mounts that resolve differently in CI vs local.
• Over-mounting the working directory onto /app and hiding dependencies.
• Ignoring truncated errors: always run without -d once to read the full cause.

Performance notes

• Build efficiently

  • Use .dockerignore to shrink build context.
  • Leverage layer caching: docker compose build --pull

• Faster local startup

  • Avoid unnecessary bind mounts on large directories.
  • Use named volumes for databases to reduce permission overhead.
  • Limit services during dev with profiles and selective up: docker compose up db api

• Reduce restart thrash

  • Add healthchecks and backoff in app startup scripts.
  • Use restart: unless-stopped only after the service starts cleanly.

Tiny FAQ

• How do I see the real failure?

  • Run: docker compose up <service> (no -d). The line after "Cannot start service" is the key.

• My container exits instantly. Is that a start error?

  • Not necessarily. The process may complete and exit 0. Check docker logs and the command/entrypoint.

• Compose says the network is missing. Do I need external?

  • Only if you want to share a pre-created network. Otherwise, let Compose create internal networks.

• Windows path errors with volumes?

  • Use absolute paths or ${PWD}. Prefer forward slashes and ensure the path is shared with Docker Desktop.