Sphinx error: Undefined label: … (if the link has no caption the label must precede a section header)

Did you Sphinx documentation project has failed with the error Undefined label: … (if the link has no caption the label must precede a section header)? This guide provides an explanation and solution to resolve the issue.

Symptom

Sphinx build failed with error similar to the following:

index.rst:4: WARNING: undefined label: foo (if the link has no caption the
label must precede a section header)

Reason

Reference :ref: points to non-existing label.

Example

The document contains :ref: reference to cmd-options label, but a label doesn’t exist in the document either project.

Welcome
=======

For full list, see :ref:`cmd-options`.

Solution

Add missing label .. _cmd-options: before respective place.

Welcome!
========

See also :ref:`cmd-options`.

.. _cmd-options:

Commandline options
-------------------

Foo has many many many options.

Label may be added even in different document, e.g. reference.rst.

Reference
==========

...a lot of text...

.. _cmd-options:

Commandline options
--------------------

Foo has many many many options.