sphinx "WARNING: more than one target found for cross-reference"

Fix Sphinx "more than one target found for cross-reference" warnings

TL;DR

A short cross-reference like 'connect' matches several documented objects, so Sphinx cannot pick one. Qualify the reference with its full dotted path (myapp.db.connect), optionally with a ~ prefix to keep the short display text, then rebuild. The warning clears because the reference now matches exactly one target.

The error

docs/index.rst:20: WARNING: more than one target found for cross-reference 'connect': could be myapp.db.connect, myapp.cache.connect

Steps

1. Collect every occurrence: sphinx-build -b html docs docs/_build 2>&1 | grep "more than one target". Expected: lines like the block above, each listing the ambiguous name and its candidate targets.

2. Open the file at the reported line and replace the short reference with the full dotted path of the intended target, e.g. write the role with myapp.db.connect instead of connect. Expected: the reference names exactly one documented object.

3. If you want the rendered text to stay short, prefix the path with ~ (e.g. ~myapp.db.connect); Sphinx links to the full target but displays only the last component. Expected: the page shows 'connect' while linking to myapp.db.connect.

4. Clean rebuild with warnings as errors: rm -rf docs/_build && sphinx-build -W -b html docs docs/_build. Expected: exit code 0 and no 'more than one target' lines.

Use this when

• a cross-reference matches two or more documented objects
• the warning lists candidate targets separated by commas
• common names (connect, run, process) exist in several modules

Not for this skill when

• 'unknown document' (toctree problem, not a cross-reference problem)
• cross-references that resolve to nothing (unresolved reference warnings)
• 'duplicate object description' (the same object documented twice)

Variant phrasings

• sphinx more than one target found for cross-reference
• sphinx ambiguous cross reference warning
• sphinx could be multiple targets reference
• sphinx cross-reference matches several objects

Why it happens

Sphinx resolves a short reference by searching every documented object for that name, and utility names like connect or run commonly exist in several modules. When the search returns more than one candidate, Sphinx links the first and warns rather than guessing silently. Qualifying with the full dotted path removes the ambiguity because the lookup becomes an exact key match against the object index.

Edge cases

• If two modules genuinely define the same public name, consider whether both should be documented or one should be private; the warning is sometimes a design smell.
• The ~ display prefix works for Python domain roles; other domains have their own display rules, so check the rendered link.
• default_role in conf.py changes which role bare backticks use; an ambiguous bare reference may need an explicit role plus the full path.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_IDtyHaONSJ9XxnvkuFFd3w