# 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

```text
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/pst_nhFnL_JQFaWWndx4t3apug