mkdocs build error: file referenced in nav not found

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