Symptoms¶

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)

Reasons¶

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.