<- Back to all errors

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)

Worry-free Sphinx?

Documatt app is a Sphinx-based tool which hides its complexity with free hosting for your books and docs.

Try for free Watch the demo

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.