mkdocs Error: Config validation failed nav key

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.

Fix MkDocs 'file referenced in nav not found' build errors

TL;DR

A nav entry points at a file MkDocs cannot find under docs_dir: a typo, a case mismatch, or a page that was moved or deleted without updating mkdocs.yml. Fix the entry or restore the file, then rebuild. The build passes because every nav path resolves to a real file.

The error

Aborted with 1 Build Errors!
ERROR - File 'guide/setup.md' not found in nav 'Guide > Setup'

Steps

1. Read the exact path from the error message. Expected: the nav path MkDocs tried, e.g. guide/setup.md.

2. Compare against the source tree: ls docs/guide/ and check spelling and letter case. On Linux, Setup.md and setup.md are different files; a build that passes on macOS fails on Linux CI for exactly this reason. Expected: you find the typo, the case difference, or the missing file.

3. Fix it: correct the nav: entry in mkdocs.yml, restore the deleted file, or move the file under docs_dir if it lives elsewhere. Expected: every nav path matches a real file inside docs/.

4. Rebuild: mkdocs build. Expected: exit code 0 and the page appears in the built site navigation.

Use this when

• mkdocs build aborts naming a file it cannot find in nav
• pages renamed or moved without updating mkdocs.yml
• builds pass on macOS but fail on Linux

Not for this skill when

• plugin 'search' is not installed (install problem, not content)
• theme 'material' not found (theme problem)
• warnings about files 'not included in nav' (those are warnings, and the fix is the reverse: add or exclude them)

Variant phrasings

• mkdocs file referenced in nav not found
• mkdocs build error nav file missing
• mkdocs aborted build errors nav
• mkdocs nav entry file does not exist

Why it happens

The nav section is an explicit map from titles to file paths, and MkDocs validates every path against the files it found under docs_dir. Anything that breaks the mapping - a typo, a rename committed without updating mkdocs.yml, a case difference invisible on macOS, a file saved outside docs/ - turns into this build error. It is a hard error rather than a warning because the navigation would otherwise link to a page that was never built.

Edge cases

• Files present under docs/ but absent from nav only produce a warning ('not included in navigation'); decide per file whether to add it to nav or leave it.
• Deeply nested nav makes typos likely; keep the nav tree shallow or generate it only if the team maintains the generator.
• After fixing, run mkdocs build --strict in CI so future nav rot fails the build instead of shipping silently.

Provenance

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

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

Thread query: mkdocs build error: file referenced in nav not found

TL;DR: A nav entry points at a file MkDocs cannot find under docs_dir: a typo, a case mismatch, or a page that was moved or deleted without updating mkdocs.yml. Fix the entry or restore the file, then rebuild. The build passes because every nav path resolves to a real file.

Not specified by the original author.

TL;DR

Add a site_name key to mkdocs.yml. It is the one required setting; every other key is optional.

Error

KeyError: 'site_name'

Steps

1. Open mkdocs.yml and look for a top-level site_name entry. Expected: it is absent or nested under another key by mistake.
2. Add site_name: Your Project Name at the top level of the file, with no indentation. Expected: the key sits at column zero like other top-level settings.
3. Validate the file parses by running mkdocs build again or python -c "import yaml; yaml.safe_load(open('mkdocs.yml'))". Expected: the config loads without errors.
4. Run the full build: mkdocs build. Expected: the site builds into the site directory.

When to use

• MkDocs aborts with KeyError naming site_name
• A new mkdocs.yml was hand-written or generated by a script
• A docs agent emitted a config without the required key

When not to use

• The error is a YAML syntax error (different message, fix the syntax)
• site_name exists but a plugin fails (the plugin is the problem)
• You are configuring a MkDocs plugin that has its own required keys

Tool compatibility

MkDocs 1.4 through 1.6. site_name has been required in every MkDocs release.

Variant phrasings

KeyError site_name after splitting config with plugins

Some config-inheritance plugins merge files; ensure the merged result still carries site_name at the top level.

mkdocs.yml exists but MkDocs says it cannot find it

You are running the command from the wrong directory. Run it where mkdocs.yml lives, or pass -f path/to/mkdocs.yml.

Why it happens

MkDocs validates the config dict and reads config['site_name'] unconditionally to title the site. A missing key raises KeyError before any building starts. Generators and agents often emit plugin-heavy configs and forget the single mandatory field.

Provenance

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

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

Thread query: mkdocs build "KeyError: 'site_name'" config error

TL;DR: Add a site_name key to mkdocs.yml. It is the one required setting; every other key is optional.