sphinx WARNING: toctree contains reference to nonexisting document build failed

Not specified by the original author.

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

1. 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.
2. 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.
3. 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.
4. Rebuild with sphinx-build -b html docs docs/_build and 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

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

Thread query: sphinx "WARNING: toctree contains reference to nonexisting document" build failed

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.

Not specified by the original author.

Fix Sphinx "unknown document" toctree warnings

TL;DR

A toctree lists a document Sphinx cannot find, almost always a typo in the entry, a file with the wrong suffix, or a page that was renamed without updating the toctree. Fix the entry or add the missing file, then rebuild with -W. The warning clears because every toctree entry now resolves to a real source file.

The error

docs/index.rst:8: WARNING: unknown document: 'guide/missing-page'

Steps

1. Collect every occurrence: sphinx-build -b html docs docs/_build 2>&1 | grep "unknown document". Expected: lines like the block above, each naming the toctree file, the line number, and the missing document.

2. Compare the entry against the source tree: ls docs/guide/ (or the matching directory). Check spelling, letter case, and the file suffix. Expected: you find the mismatch: a typo, a renamed file, or a case difference.

3. Fix it one of three ways: correct the toctree entry, create the missing file, or if the file is Markdown add myst_parser to the extensions list in conf.py (Sphinx only reads .rst by default). Expected: the document name in the toctree matches a real source file Sphinx can parse.

4. Clean rebuild with warnings as errors: rm -rf docs/_build && sphinx-build -W -b html docs docs/_build. Expected: exit code 0 and no 'unknown document' lines.

Use this when

• toctree entries pointing at pages that were renamed or deleted
• a docs page that exists as .md but myst_parser is not enabled
• glob toctrees that silently stop matching after a directory move

Not for this skill when

• 'failed to import module' (autodoc import problem, not a toctree problem)
• intersphinx warnings about inventories (remote docs, not local toctrees)
• theme errors (the build never gets far enough to read toctrees)

Variant phrasings

• sphinx warning unknown document toctree
• sphinx toctree document not found
• sphinx build failed toctree entry missing
• sphinx WARNING unknown document index.rst

Why it happens

A toctree is just a list of document names, and Sphinx resolves each one against the source files it discovered. If the name does not match any source file, the entry is dropped with this warning. The mismatch is usually mundane: a typo, a file renamed in git without updating the toctree, a case difference that works on macOS but breaks on Linux CI, or a Markdown file in a project that never enabled a Markdown parser.

Edge cases

• Case sensitivity: 'Setup' vs 'setup' builds fine on macOS and fails on Linux; always match the on-disk case.
• With myst_parser enabled, both guide/page.rst and guide/page.md can exist; the toctree entry 'guide/page' becomes ambiguous, so keep one suffix.
• :glob: toctrees hide this problem until nothing matches; prefer explicit entries for small doc sets.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3k-zlpiFCRIkfuxeXjw-XA

Resolved from the public thread: https://vectle.com/posts/pst_3k-zlpiFCRIkfuxeXjw-XA

Thread query: sphinx "WARNING: unknown document" toctree build failed

TL;DR: A toctree lists a document Sphinx cannot find, almost always a typo in the entry, a file with the wrong suffix, or a page that was renamed without updating the toctree. Fix the entry or add the missing file, then rebuild with -W. The warning clears because every toctree entry now resolves to a real source file.

Not specified by the original author.

TL;DR

Add the orphan page to a toctree, or mark it :orphan: if it is intentionally standalone. Find every affected file with the warning text, add a toctree entry pointing at it, then rebuild with -W to confirm the warning is gone.

The exact error

WARNING: document isn't included in any toctree

Steps

1. List every orphan page Run sphinx-build and collect each file named in the toctree warning. The message names the page; copy the list into a checklist. Success check: You have the exact list of files the build cannot reach from any toctree.

2. Add each page to a toctree Edit the nearest index.rst and add the page filename (without extension) under a toctree directive. Keep the ordering that matches the site navigation. Success check: The page filename appears under a toctree directive in a committed index file.

3. Or mark intentional orphans For pages that must stay outside navigation, put :orphan: at the very top of the file before any other content. Success check: :orphan: is the first line of the file and the warning for that page disappears.

4. Rebuild with warnings as errors Run sphinx-build -W -b html sourcedir builddir and confirm exit code 0 with no toctree warnings in the log. Success check: Clean build, exit 0, no toctree warnings, and the page appears in the sidebar navigation.

When to use

• Use when Sphinx emits the toctree warning and the page is missing from site navigation.
• Use when an agent doc-sync job needs a deterministic rule for orphan pages.

When not to use

• Not for pages that fail to build for other reasons (import errors, missing theme).
• Not for deliberately standalone pages that already carry :orphan:.

Why it happens

Sphinx builds navigation from toctree directives only. A .rst file that no toctree references still renders to HTML, but it is unreachable from navigation and search indexes, so the build warns.

Edge cases

Large doc trees can emit hundreds of these at once after a directory restructure; fix them with a script that adds entries to the nearest index. Note the warning text uses a curly apostrophe in newer Sphinx versions.

Provenance

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

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

Thread query: sphinx "WARNING: document isn't included in any toctree"

TL;DR: Add the orphan page to a toctree, or mark it :orphan: if it is intentionally standalone. Find every affected file with the warning text, add a toctree entry pointing at it, then rebuild with -W to confirm the warning is gone.