Docker Compose — Common Compose Errors

A reference of the most common Docker Compose errors and how to fix them.

YAML Syntax Errors

yaml: line 5: did not find expected key

Cause: Incorrect indentation or missing colons.

Fix: Use 2 spaces (never tabs). Validate with:

docker compose config -q

Service Not Found

service "apii" is not defined in the Compose file

Cause: Typo in service name.

Fix: Check docker compose config --services for valid names.

Image Not Found

Error: pull access denied for myapi, repository does not exist

Cause: Image doesn’t exist or wrong tag.

Fix: Check image name/tag. For local builds, ensure build: is set.

Build Context Error

failed to solve: failed to read dockerfile

Cause: Dockerfile not found in build context.

Fix: Check build.context path and build.dockerfile name:

ls ./api/Dockerfile    # Verify file exists

Orphan Container Warning

WARNING: Found orphan containers (myapp-old-service-1)

Cause: Service was removed from compose.yml but containers still exist.

Fix:

docker compose up -d --remove-orphans

Permission Denied

Got permission denied while trying to connect to the Docker daemon socket

Fix (Linux):

sudo usermod -aG docker $USER
# Log out and back in

Version Warning

WARN[0000] /path/compose.yml: `version` is obsolete

Cause: version: key is deprecated in modern Compose.

Fix: Remove the version: line from your compose file.

Environment Variable Not Set

WARN[0000] The "MY_VAR" variable is not set. Defaulting to ""

Fix: Set the variable in .env, shell, or use a default:

image: myapi:${VERSION:-latest}

Container Already Exists

Error: container myapp-api-1 already exists

Fix:

docker compose rm -f
docker compose up -d

Summary

Error	Quick Fix
YAML syntax	docker compose config -q
Service not found	Check service name spelling
Image not found	Verify image:tag exists
Build failed	Check Dockerfile path
Orphans	--remove-orphans
Permission	Add user to docker group
Version warning	Remove version: key
Variable unset	Add to .env or use default

---

Quick Reference

Item	Detail
YAML error	docker compose config -q to validate
Image not found	Check image name and tag
Build failed	Verify Dockerfile path and context
Orphans	docker compose up –remove-orphans
Permissions	sudo usermod -aG docker $USER
Var not set	Use ${VAR:-default} syntax