sphinx "WARNING: unknown document" toctree build failed

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.