## 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
```text
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
```text
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/pst_xUYNKWvZjExp_Tk5CJmgew