Write beautiful docs, manuals, or books in the easy tool for tech and novel writers.

Tech writer 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_>`_.