TechWriter at work blog logo

TechWriter at work blog

Living and writing documentation at Documatt, small team of programmers that write documentation too.

Duplicate target name, cannot be used as a unique reference#

Symptoms#

Sphinx build failed with the error similar to:

WARNING: Duplicate target name, cannot be used as a unique reference: "introduction".

Reasons#

You created reference (link) that points toward to multiple targets.

Example#

You can created link target in many ways. For example, Sphinx creates automatically targets for all sections, footnotes, and citations. The following document has two section named “Introduction”:

Welcome!
========

Introduction
------------

Introduction
------------

This isn’t problem until you create a link to “Introduction” section - but which one?

Have a look at `Introduction`_.

Solution#

To prevent target ambiguity, add custom .. _labels: to sections that are unique:

Welcome!
========

.. _intro-one:

Introduction
------------

.. _intro-two:

Introduction
------------

Have a look at `Introduction <intro-two_>`_.