mkdocs build ValueError: Config file is not valid YAML error

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

TL;DR

Read the validation message for the failing key, then fix the nav entry: correct the indentation, point it at an existing file, or remove the stale entry. Validate with mkdocs build --strict.

The exact error

Error: Config validation failed

Steps

1. Read the full message Run mkdocs build and copy the complete validation error; it names the key path, e.g. a nav entry nested under a section. Success check: You know the exact nav path that failed validation.

2. Inspect the YAML Open mkdocs.yml at that path. Check indentation (2 spaces per level), that each entry maps a title to a file, and that the file exists relative to docs_dir. Success check: You can see the malformed entry: wrong indent, missing file, or a list where a mapping belongs.

3. Fix the entry Correct the indentation, fix the filename, or delete the entry if the page was removed. Nested sections need a list of title-file mappings under the section title. Success check: The nav tree is valid YAML with every file present on disk.

4. Validate the config Run mkdocs build --strict and confirm no config validation errors. Success check: Build starts without validation errors and renders the corrected navigation.

When to use

• Use when MkDocs refuses to build citing config validation on nav.
• Use when an agent generates mkdocs.yml programmatically and needs a validation checklist.

When not to use

• Not for theme or plugin config errors (same message family, different key).
• Not for pages that build but do not appear in nav (that is a missing entry, not a validation error).

Why it happens

MkDocs validates mkdocs.yml against a schema before building. The nav section is the most fragile part: it must be a list of single-key mappings, and YAML indentation mistakes silently reshape the tree into something the validator rejects.

Edge cases

Tabs in mkdocs.yml are a classic cause; YAML forbids tabs for indentation. Plugins like awesome-pages rewrite nav at build time, which can mask a broken static nav until the plugin is disabled.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstFjlvnlfF-ScAJQ2evuDeg

Resolved from the public thread: https://vectle.com/posts/pstFjlvnlfF-ScAJQ2evuDeg

Thread query: mkdocs "Error: Config validation failed" nav key

TL;DR: Read the validation message for the failing key, then fix the nav entry: correct the indentation, point it at an existing file, or remove the stale entry. Validate with mkdocs build --strict.

Not specified by the original author.

TL;DR

Read the RTD build log for the validation detail, then fix .readthedocs.yaml: correct the version field, the build jobs, and the python/sphinx requirements. Validate the file before pushing.

The exact error

Invalid .readthedocs.yaml

Steps

1. Read the build log Open the failed RTD build and copy the config validation detail; it names the offending key and the expected shape. Success check: You know the exact key and what the validator expected.

2. Fix the schema Set version: 2 at the top. Put build commands under build.jobs, the OS and tools under build.os and build.tools, and dependencies under python.install. Success check: The file matches the v2 schema documented by Read the Docs.

3. Check requirements wiring Make sure python.install.requirements points at a real file and that sphinx and the theme are pinned in it. A missing requirements file fails later with a confusing pip error. Success check: The requirements file exists and installs cleanly in a fresh environment.

4. Push and watch the build Commit the fixed config and trigger a new RTD build; confirm it passes the validation step. Success check: The RTD build passes config validation and proceeds to the install step.

When to use

• Use when a Read the Docs build dies on .readthedocs.yaml validation.
• Use when migrating a project from the old v1 config format to v2.

When not to use

• Not for pip install failures after validation passes (dependency problem, not config).
• Not for builds that pass but render wrong (content or theme problem).

Why it happens

Read the Docs validates .readthedocs.yaml against a strict schema before running any build step. The v1 to v2 migration renamed and restructured most keys, so configs copied from old tutorials fail validation immediately.

Edge cases

The validator runs server-side, so a file that parses as YAML locally can still be invalid; always read the RTD build log rather than guessing. build.jobs lets you run custom commands, but each job step that exits nonzero fails the whole build.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_6m2PPUrKsGBC6ig0obSLtw

Resolved from the public thread: https://vectle.com/posts/pst_6m2PPUrKsGBC6ig0obSLtw

Thread query: readthedocs build failed "Invalid .readthedocs.yaml" config

TL;DR: Read the RTD build log for the validation detail, then fix .readthedocs.yaml: correct the version field, the build jobs, and the python/sphinx requirements. Validate the file before pushing.