sphinx "WARNING: undefined label" rst cross-reference
Fixes Sphinx undefined-label warnings that break internal cross-references. The skill shows how to trace the dangling :ref:, verify the target label exists exactly once, and rebuild clean. It covers typos, moved sections, and labels lost in refactors.
TL;DR
Find the :ref: target named in the warning, then fix the typo, restore the moved label, or remove the stale reference. Labels must match character for character. Rebuild with -W to confirm zero undefined-label warnings.
The exact error
WARNING: undefined label: 'getting-started'Steps
Capture the label name Run the build and copy the exact label string from each undefined-label warning, including hyphens and case. Success check: You have the exact label text Sphinx could not resolve.
Search the source tree for it Grep the docs for the label definition, which looks like .. _label-name: on its own line. Check for typos, renames, or deleted sections. Success check: You know whether the label is missing, misspelled, or defined twice.
Fix or remove the reference Correct the :ref: to match the real label, restore the label above the moved section, or delete the reference if the section is gone. Success check: The :ref: target matches an existing unique label definition.
Rebuild with warnings as errors Run sphinx-build -W -b html and confirm a clean exit with no undefined-label lines. Success check: Exit 0, no warnings, and the rendered link jumps to the right section.
When to use
- Use when Sphinx warns about undefined labels and internal links render as plain text.
- Use when an agent refactors docs and needs to verify no cross-references broke.
When not to use
- Not for intersphinx cross-project references (those need inventory fixes).
- Not for duplicate-label warnings (the label exists, just more than once).
Why it happens
Sphinx resolves :ref: targets against labels defined with .. _name: directives. Renaming a section heading without updating its label, or deleting the labeled section, leaves the reference dangling and the build warns.
Edge cases
Labels are case-sensitive and whitespace-sensitive; a trailing space in the label definition is invisible in most editors but breaks the match. autosectionlabel generates labels from headings automatically, which shifts the failure mode from missing labels to duplicate ones.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_a1nsOy7MqpEi6kksfz0rQg