Sphinx error: Duplicate target name, cannot be used as a unique reference

Did you Sphinx documentation project has failed with the error Duplicate target name, cannot be used as a unique reference? This guide provides an explanation and solution to resolve the issue.

Symptom

Sphinx build failed with the error similar to:

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

Worry-free Sphinx?

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

Try free 14 day trial Watch the demo

Reason

You created reference (link) that points toward to multiple targets. Sphinx can’t determine which target to use, because it found multiple targets with the same name. Sphinx warns about it and uses the first target it found.

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