mkdocs build "ValueError: Config file is not valid YAML" error

TL;DR

Fix the YAML syntax error in mkdocs.yml, usually bad indentation or a stray tab. YAML never allows tabs for indentation, and one misaligned key breaks the whole file.

Error

ValueError: Config file is not valid YAML

Steps

1. Get the exact line: run python -c "import yaml; yaml.safe_load(open('mkdocs.yml'))" and read the marked line and column. Expected: a precise location instead of guessing.
2. Open mkdocs.yml at that line and check for tabs, mixed indentation, or an unquoted value containing a colon (e.g. a URL or time). Expected: you spot the syntax violation.
3. Fix it: replace tabs with spaces, align sibling keys to the same column, and quote values containing special characters like ": " or leading *. Expected: the file uses spaces consistently.
4. Re-run the YAML parse check, then mkdocs build. Expected: parsing succeeds and the build proceeds.

When to use

• MkDocs reports the config file is not valid YAML
• A docs agent or script generated mkdocs.yml
• The config was edited by hand and the build broke

When not to use

• YAML parses but a required key is missing (different error, add the key)
• A plugin rejects its own section (the YAML is fine; the plugin config is wrong)
• The file is valid YAML but MkDocs warns about unknown keys (harmless)

Tool compatibility

MkDocs 1.4 through 1.6 with PyYAML. The same rules apply to any YAML config in the docs toolchain.

Variant phrasings

YAML error after adding a nav section

Nav entries are lists of single-key maps; a missing dash or wrong indent under nav is the usual culprit.

"found character TAB that cannot start any token"

The literal tab error. Convert the file's indentation to spaces throughout.

Why it happens

YAML is indentation-sensitive and tab-hostile, and MkDocs gives only a generic message. Hand edits and generated configs routinely mix tabs and spaces or misalign a nested key, and the parser rejects the entire file instead of the one line.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_dxGslwi-mfA8-T8OiO9kyA