Use this Docker Compose Validator to check docker-compose.yml files before you run them in production. It helps you catch YAML syntax issues (indentation and whitespace problems), schema mistakes, and common Compose configuration errors in services, networks, and volumes.
Paste your compose file into the editor or upload a YAML file, then click Validate. You’ll get a clear list of issues so you can fix them before docker compose up fails. This is especially useful for multi-service stacks, CI pipelines, and templated compose files that change between environments. Privacy note: validation runs in-browser in the tool UI.
Validate Docker Compose Files
Edit Docker Compose File
What this validator checks
- Basic structure checks (e.g., missing top-level services:)
- Extracts defined services, networks, and volumes
- Flags a few common mistakes (e.g., questionable service naming)
- Notes when version: is missing (informational)
How to validate docker-compose.yml
- Paste your compose file into the editor (or upload a file).
- Click Validate.
- Review the issues list.
- Fix the compose file and validate again.
- Copy the corrected compose file back into your repo.
Docker Compose examples
Example: Minimal valid compose file
services: web: image: nginx:alpine ports: - "8080:80"
Example: Common YAML indentation error
Broken:
services: web: image: nginx:alpine
Fix:
services: web: image: nginx:alpine
Example: Volumes usage
services: db: image: postgres:16 volumes: - dbdata:/var/lib/postgresql/data volumes: dbdata:
Common Docker Compose errors (and fixes)
| Error | Likely cause | Fix |
|---|---|---|
| “mapping values are not allowed here” | YAML indentation or colon issues | Fix indentation; quote strings containing : |
| Missing services | Wrong top-level structure | Ensure top-level services: exists |
| Invalid port mapping | Wrong format | Use “HOST:CONTAINER” strings |
| Volume not found | Missing volumes: section | Define named volumes at the bottom |
| depends_on doesn’t wait for readiness | Startup order vs readiness | Use healthchecks + app retries |
Best practices
- Keep compose files small; split by environment when needed.
- Prefer explicit image tags (avoid latest in production).
- Add healthchecks for services that must be “ready”.
- Validate in CI before deploying.
Common questions
Does Docker Compose still require the version: field?
On modern Docker Compose (Compose Specification), the version field is optional. Many examples still include it, and older tooling may expect it, so it’s common to keep it for compatibility.
What’s the difference between Compose v2 and v3?
Historically, v2/v3 referred to file formats and Swarm features. Today, Docker Compose follows the Compose Specification and many keys work across versions—focus on what your runtime supports.
Why do I get YAML indentation errors?
YAML is whitespace-sensitive. A single wrong space can break structure (e.g., services under services:). Validate, then fix indentation to consistent 2 spaces.
Why does depends_on not wait for readiness?
depends_on controls startup order, not service readiness. Use healthchecks and have your app retry connections until dependencies are ready.
How do I validate multiple compose files (overrides)?
Compose supports multiple files with -f flags (e.g., docker-compose.yml + docker-compose.prod.yml). This tool validates a single file at a time—merge or validate each file separately.
Can I validate .env substitutions?
This tool can validate the syntax, but it can’t resolve your environment variables at runtime. Always run docker compose config to see final resolved output.
What’s the difference between named volumes and bind mounts?
Named volumes are managed by Docker and live outside your project folder. Bind mounts map a host path (like ./data) into the container.
Can this validator detect invalid images or registries?
No. It validates file structure and common schema issues, but it doesn’t pull images or verify registry credentials.
Is my compose file uploaded to a server?
No—validation is performed in-browser in this tool UI. Your compose contents are not uploaded.
What does this validator check for?
It checks for common structure issues (like missing services:), extracts services/networks/volumes, and flags a few common mistakes. It’s designed as a fast preflight, not a full engine-level config resolver.
Related tools
- JSON Formatter — validate JSON used by apps in containers
- Base64 Encoder/Decoder — encode config snippets safely
- Hash Generator — integrity checks for artifacts
- SSL Checker — verify HTTPS endpoints you deploy