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.

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.