Paste a docker-compose.yml or compose.yaml to check it instantly. The validator catches YAML syntax errors, unknown or misspelled keys, wrong value types, broken links between services, networks, volumes and secrets, host port clashes and deprecated options, each with the line number and a fix.
Last updated:
1
Loading the YAML engine…
Services found
Service
Image / build
Ports
Depends on
Advertisement
Advertisement
How to use the Docker Compose Validator
Paste your Compose file into the editor, upload docker-compose.yml, or load one of the samples.
Read the summary: it shows whether the file is valid and how many errors, warnings and tips were found.
Click an issue to jump to the matching line; errors are marked in red and warnings in amber.
Fix the problems in the editor; the file is checked again automatically as you type.
Filter or copy the report to share it in a pull request or ticket, then run docker compose config locally for a final check.
Common Docker Compose errors and how to fix them
Most broken Compose files fail for a handful of reasons. The table lists the messages you are likely to see here, what causes them and the usual fix.
Problem
Typical cause
Fix
Bad indentation
A key is indented with a different number of spaces than its siblings, or a tab was used
Use spaces only and keep every key of one service at the same column
Unknown key
A typo (enviroment, depend_on) or a key placed at the wrong level
Use the suggested spelling; custom keys must start with x-
Named volume not declared
data:/app/data refers to a named volume that is missing from the top-level volumes:
Add volumes: {data: {}}, or write ./data:/app/data for a bind mount
Network not declared
A service joins a custom network that is not defined
Add it under top-level networks:; only default exists automatically
Service has neither image nor build
The service only sets ports or environment
Add image: name:tag or build: ./folder
Host port already published
Two services map the same host port, for example both use "80:…"
Give each a different host port, or bind them to different IPs
Circular dependency
A depends on B and B (directly or indirectly) depends on A
Remove one direction; use healthchecks and retries instead of mutual waits
Invalid duration
interval: 30 seconds or timeout: 5
Write a number with a unit: 30s, 1m30s, 500ms
Boolean expected
privileged: yes is a string in YAML 1.2
Use true or false
Deprecated and legacy Compose keys
The Compose Specification replaced the separate version 2 and version 3 file formats. A few older options still work but are no longer recommended:
version: obsolete. Compose v2 ignores it and warns about it. Delete the line; the newest features are always available.
links: legacy. Every service on a shared network can already reach the others by service name, for example db:5432. Use depends_on for start order and network aliases for extra hostnames.
external_links: legacy. Attach both projects to the same external network instead.
external: {name: …}: deprecated. Write name: shared_net and external: true on the network or volume.
Tips for a healthy Compose file
Pin image tags (postgres:16-alpine rather than postgres or :latest) so every deploy runs the same version.
Add a healthcheck to databases and caches and use condition: service_healthy in depends_on, so dependent services start only when they can connect.
Keep secrets out of the file: reference ${DB_PASSWORD} from an untracked .env file, or use the top-level secrets section and *_FILE variables.
Do not publish database ports unless you need them from the host; containers on the same network reach each other without ports. If you do, bind to 127.0.0.1.
Avoid container_name unless another tool needs a fixed name; it blocks scaling and can clash between projects.
Run docker compose config after editing to see the final file with variables and override files merged.
Frequently asked questions
What does this Docker Compose validator check?
It parses the file as YAML, then compares every key and value with the Compose Specification used by Docker Compose v2: allowed keys, value types, enums such as restart policies and depends_on conditions, and duration formats. After that it checks the relationships between parts of the file, for example that every network, named volume, secret and dependency a service uses is actually defined.
Is the version key still needed in docker-compose.yml?
No. Docker Compose v2 follows the Compose Specification, which treats the top-level version key as obsolete. Compose ignores it and prints a warning that the attribute is obsolete, so you can delete the line. The validator reports it as a deprecated key.
Why does it say my named volume is not declared?
A volume entry such as db_data:/var/lib/mysql uses a named volume because the source has no slash or dot. Named volumes must be listed in the top-level volumes section (an empty entry like db_data: is enough). If you meant a folder on your computer, write it as a path such as ./db_data:/var/lib/mysql.
How is this different from docker compose config?
docker compose config is the authoritative check because it runs the real Compose engine, resolves environment variables and merges override files. This tool works without Docker installed, explains each problem in plain language, adds best-practice tips and never sends the file anywhere. Use both: this one while editing, docker compose config before you deploy.
Does the validator replace ${VARIABLES} with values?
No. Variables are left as written because their values come from your shell or .env file. The validator checks that each interpolation is well formed, for example ${VAR}, ${VAR:-default} or ${VAR:?message}, and skips type checks on values that contain a variable.
Why should port mappings be quoted?
YAML 1.1 parsers read an unquoted value such as 22:22 as a base-60 number. Docker Compose v2 uses YAML 1.2 and handles it correctly, but other tools in your pipeline may not. Quoting every mapping, for example "8080:80", avoids the problem everywhere.
Is my Compose file uploaded?
No. The validator and the YAML parser run in your browser. The file is never sent to a server, so it is safe to check files that contain internal hostnames or credentials.
Are all the tools on FreeToolCabin tested for quality and accuracy?
Yes! Every tool on our site undergoes automated Q/A testing in real browser environments to ensure high precision, correct output, and zero errors. If you happen to spot a bug or have a suggestion, please contact us at [email protected] and our team will review it right away.