sphinx "WARNING: toctree contains reference to nonexisting document" build failed
Fixes Sphinx builds that fail when a toctree entry points at a document file that does not exist. Use when the build log shows the nonexisting-document toctree warning. Not for autodoc import failures or theme errors.
TL;DR
Delete or correct the stale toctree entry, or create the missing document file, then rebuild. Each toctree entry must match an existing source file name exactly, without the file extension. The warning names the offending entry so you can find it in seconds.
Error
WARNING: toctree contains reference to nonexisting document 'api/client'Steps
- Copy the document name from the warning and search your source tree for a file with that name plus a source suffix:
find docs -name "client*". Expected: you see which expected file is absent. - Open the file containing the toctree directive (often index.rst) and locate the entry that matches the warning text. Expected: the entry is visible under a
.. toctree::block. - If the document was renamed, update the entry to the new name. If it was deleted on purpose, remove the entry line. If it should exist, create the file. Expected: every toctree entry now matches a real file.
- Rebuild with
sphinx-build -b html docs docs/_buildand confirm the warning is gone from the output. Expected: zero toctree warnings in the build log.
When to use
- Sphinx build log contains "toctree contains reference to nonexisting document"
- A docs page was renamed or deleted and the index was not updated
- A new toctree entry was added before its file was created
When not to use
- The warning is about a missing image or download file, not a document
- The document exists but fails to import under autodoc (different failure)
- You want glob-style toctrees, which need explicit
:glob:option handling instead
Tool compatibility
Sphinx 5.x through 8.x, any builder. Also applies to MyST Markdown toctrees, where the same rule covers .md source files.
Variant phrasings
toctree references a document that was moved
WARNING: toctree contains reference to nonexisting document 'guide/setup'Same fix: update the entry to the new path after the move.
toctree warning after a branch merge
The entry is correct on one branch but the file only exists on another. Check out the right branch or merge the missing file before rebuilding.
Why it happens
Sphinx resolves each toctree entry to a source document at build time. When a file is renamed, moved, or deleted without updating the toctree, the reference dangles and Sphinx warns instead of guessing. Case sensitivity matters on Linux builds: API/client and api/client are different documents.
Provenance
Resolved from the public thread: https://vectle.com/posts/pstxUYNKWvZjExpTk5CJmgew