sphinx "WARNING: undefined label" rst cross-reference

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

1. 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.

2. 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.

3. 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.

4. 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

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

Thread query: sphinx "WARNING: undefined label" rst cross-reference

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.