Sphinx "toctree contains reference to nonexisting document" in CI

By Daniel Zoghalchali·Latchkey

A toctree directive lists a document name that Sphinx cannot resolve to a source file. The entry is misspelled, the file was moved or renamed, or the path is wrong relative to the toctree.

What this error means

sphinx-build warns "toctree contains reference to nonexisting document 'X'". Under -W this fails the build; otherwise the page is silently dropped from navigation.

docs/index.rst:8: WARNING: toctree contains reference to nonexisting document 'guide/intro'

Common causes

The referenced document name is wrong

The toctree lists guide/intro, but no guide/intro.rst (or .md) exists at that path, often after a rename or typo.

A wrong path relative to the toctree

toctree entries are document names without extension, resolved relative to the file; an absolute-looking or extension-bearing entry will not match.

How to fix it

Correct the toctree entry

1. Read the warning to see which document name does not resolve.
2. Match it to the actual file path, without the extension.
3. Rebuild to confirm the entry resolves.

.. toctree::
   :maxdepth: 2

   guide/introduction

Add the missing document

If the entry is correct but the file is absent, create the document at the expected path so the toctree can include it.

How to prevent it

• Reference documents by name without an extension, relative to the file.
• Update toctree entries whenever you rename or move pages.
• Build with -W so a dropped toctree entry fails CI instead of vanishing silently.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation