yaml: line N: did not find expected key | YAML indentation or syntax error | Check line N for tabs (use spaces), missing colons, or unquoted special characters |
services is required | Missing services: top-level key | Add services: as the top-level element |
service "X" refers to undefined network "Y" | Network used but not declared | Add network Y to top-level networks: section |
service "X" refers to undefined volume "Y" | Named volume used but not declared | Add volume Y to top-level volumes: section |
port is already allocated | Host port in use by another container or process | Find occupant: lsof -i :PORT or ss -tlnp | grep PORT. Use a different host port |
Bind for 0.0.0.0:PORT failed | Same as above — port conflict | Same fix as above |
dependency "X" is not a valid service | depends_on references nonexistent service | Check service name spelling in depends_on |
Found orphan containers | Services removed or project name changed | Run docker compose down --remove-orphans |
variable "X" is not set | Interpolation variable undefined | Define in .env file, or use ${X:-default} syntax |
invalid interpolation format | Malformed variable syntax | Check for unescaped $. Use $$ for literal dollar sign |
build path /path does not exist | Build context directory missing | Verify context: path exists relative to compose.yaml |
Cannot locate specified Dockerfile | Dockerfile path wrong | Check dockerfile: is relative to context:, not compose.yaml |
pull access denied for X | Image not found or authentication required | Run docker login. Verify image name and tag |
no matching manifest for linux/amd64 | Image not available for platform | Add platform: to service or use compatible image |
service "X" has neither an image nor a build context | Service needs image or build | Add image: or build: to the service definition |
"version" is obsolete | Deprecated version field | Remove the version: line entirely |
invalid service name "X" | Service name contains invalid characters | Use only [a-zA-Z0-9._-], start with letter or digit |
Compose file not found | No compose.yaml in directory | Create compose.yaml or use -f flag to specify path |
container name "X" is already in use | Stale container with same name exists | Run docker compose down first, or docker rm X |
network X declared as external but could not be found | External network does not exist | Create it: docker network create X |
volume X declared as external but not found | External volume does not exist | Create it: docker volume create X |
