One wrong space in a YAML file can take down a CI pipeline, refuse a Kubernetes deployment, or cause a Docker Compose run to fail silently. The error message you get back — "mapping values are not allowed here" or "could not find expected ':'" — rarely tells you what actually went wrong. A yaml lint check catches those problems before they cause damage, giving you the exact line and the reason in plain language.
What a YAML Linter Actually Does
People use "lint," "parse," and "validate" interchangeably, but they mean different things.
A parser checks whether the file can be read at all. If the parser fails, you get an error. If it succeeds, you get a data structure — even if that structure is wrong in ways the parser can't detect.
A validator goes further: it checks the structure against a schema, confirming that required keys exist and values are the right type.
A linter covers both of those layers and adds style checks: consistent indentation depth, no duplicate keys, no tabs where spaces are required. It catches problems a parser would silently accept.
The 5 Errors That Break Most YAML
1. Tabs Instead of Spaces
The YAML specification forbids tab characters for indentation. Every major parser rejects them.
# Broken — tab before "name"
server:
name: api
# Fixed — two spaces
server:
name: api
Most editors insert tabs by default unless you configure them. Set "indent with spaces" for .yml and .yaml files.
2. Inconsistent Indentation Levels
YAML uses indentation to express hierarchy. Mixing two-space and four-space levels breaks the parent-child relationship the parser expects.
# Broken — "port" indented 4 spaces inside a 2-space block
server:
name: api
port: 8080
# Fixed — consistent 2-space nesting
server:
name: api
port: 8080
3. Missing Colon After a Key
Every key-value pair needs a colon followed by a space. Drop either one, and the parser treats the whole line as a bare string.
# Broken — no colon after "host"
server:
host localhost
# Fixed
server:
host: localhost
4. Unquoted Strings with Special Characters
Colons, hash signs, and @ symbols have special meaning in YAML. Use them unquoted inside a value and the parser misreads the line.
# Broken — the colon in the URL confuses the parser
redirect: https://example.com/path
# Fixed — wrap the value in quotes
redirect: "https://example.com/path"
The same rule applies to # (starts an inline comment) and @ in certain positions.
5. Duplicate Keys in the Same Mapping
Most parsers won't error on duplicate keys — they'll silently keep one value and discard the other. A linter flags it. The behavior depends on which key "wins," and that varies by library.
# Broken — "timeout" appears twice
server:
timeout: 30
timeout: 60
# Fixed — pick one
server:
timeout: 60
How to Find the Broken Line in Seconds
Scrolling through a 200-line docker-compose.yml hunting for a rogue tab is not a workflow. Here's a faster path.
Paste your YAML into the YAML Validator. If there's a problem, a red banner appears with the exact line number and the parser's error message. Click to jump to that line, fix it, and the banner turns green. The whole process runs in your browser — your config never leaves your machine.
For format conversion alongside validation, the JSON to YAML Converter lets you draft in JSON and convert to YAML in one step, which sidesteps hand-indentation errors entirely. If your config pipeline also involves JSON, the JSON Validator runs the same kind of check on the JSON side. Teams working across multiple config formats can also use the TOML to JSON Converter and the JSON Formatter without leaving the browser.
FAQ
What's the difference between YAML linting and validation?
Linting and validation both check your YAML, but at different layers. Validation confirms the file parses correctly and, optionally, that its structure matches a schema. Linting does all of that and adds style and consistency checks — catching duplicate keys, mixed indentation depths, and tab characters that a parser might silently accept. Think of linting as the stricter superset.
Why does YAML forbid tabs for indentation?
The YAML 1.2 specification explicitly prohibits tab characters because different editors interpret tab width differently — one tool may render a tab as 4 spaces, another as 8. YAML's indentation carries structural meaning, so ambiguous whitespace would mean the same file parses differently across environments. Spaces have a fixed width, which removes that ambiguity. See section 6.1 of the YAML spec for the formal rule.
How do I find which line is causing my YAML error?
Paste your YAML into the YAML Validator. It parses the file in your browser and returns the exact line number and a plain-language description of the problem. In a terminal, python3 -c "import yaml, sys; yaml.safe_load(open(sys.argv[1]))" yourfile.yaml prints line and column numbers. Most CI platforms also surface the line in their runner logs — look for "line N, column M" in the error output.
Conclusion
YAML errors are frustrating precisely because the error messages describe symptoms, not causes. Knowing the five patterns that break most files — tabs, inconsistent indentation, missing colons, unquoted specials, and duplicate keys — lets you fix problems in seconds instead of minutes. Start with the YAML Validator to get the exact line number, then apply the fix. Your next deployment will thank you.
