YAML's readability comes from using indentation as syntax, and that is also where most of its errors come from. A single space can change what a document means, and error messages often point at a line near, but not at, the real mistake. Here are the common failures and how to fix each.
Find the line first
Docento's Text & Markdown Editor checks .yml and .yaml files as you type and reports the error with a line number, such as "YAML: Line 7: ...". Click the message to jump there. Always inspect the line above the reported one as well, since YAML parsers often detect a problem only when they reach the next line.
1. Tabs for indentation
The YAML specification forbids tab characters for indentation. A tab that looks like four spaces in your editor will make the parser fail with a message about a tab character or "found character that cannot start any token". Fix: replace tabs with spaces. Set your editor to insert spaces when you press Tab, and turn on visible whitespace to find strays.
2. Inconsistent indentation
All siblings must be indented by the same amount:
server:
host: localhost
port: 8080
The port line is indented one space more than host, so the parser reports something like "mapping values are not allowed here" or "bad indentation of a mapping entry". Align them. Use a consistent number of spaces per level; two is conventional.
3. Missing space after the colon
name:docento
Without the space, this is a single string name:docento, not a key and value. Write name: docento.
4. A colon inside an unquoted value
title: Release notes: version 2
The second colon followed by a space is read as a new mapping, which triggers "mapping values are not allowed here". Quote the value: title: "Release notes: version 2". The same applies to values containing #, which starts a comment, and values beginning with characters like *, &, !, %, @ or a backtick.
5. List items at the wrong level
steps:
- name: build
run: make
- name: test
The second dash is indented differently from the first. List items under a key can be indented or flush with the key, but must be consistent within the list. The error often reads "did not find expected '-' indicator" or "expected ".
6. A dash missing or extra
A common edit mistake is deleting the dash on a list item, which turns two keys into a single mapping, or leaving a dash where a mapping value was intended. Compare with siblings.
7. Unbalanced quotes and brackets
An unclosed " or ' swallows the rest of the file until the parser finds another quote. Flow collections, such as [a, b or {x: 1, need their closing bracket. The reported line is often the end of the file; search backwards for the opening.
8. Duplicate keys
Two identical keys at the same level are invalid in the specification, and some parsers reject them while others quietly keep the last one. Remove or merge them.
9. Special characters and encoding
Non-breaking spaces copied from web pages look like normal spaces but are not whitespace to the parser. A byte order mark at the start can also cause trouble in some tools. Retype the whitespace, or retype the line.
A repeatable method
- Read the first error only; later ones are often side effects.
- Check indentation of the reported line and the previous one.
- Look for tabs and mismatched quotes.
- Fix and re-check before moving on.
Prevention
- Edit with a YAML-aware tool and validate before committing.
- Use an editor setting that shows whitespace.
- Quote strings that contain colons, hashes or leading special characters.
- Keep configuration files short and break large ones up.
Takeaway
Most YAML errors are tabs, uneven indentation, missing spaces after colons, unquoted special characters or unbalanced quotes. Locate the reported line and the one before it, fix one error at a time, and re-validate.
