intersphinx "failed to reach any of the inventories" warning

Not specified by the original author.

Fix intersphinx "failed to reach any of the inventories" warnings

TL;DR

Intersphinx downloads each project's objects.inv at build time, and this warning means every URL it tried was unreachable: the docs moved, the URL is wrong, or the build network blocks outbound requests. Verify each inventory URL by hand, fix or drop the dead ones, then rebuild. Links resolve again because intersphinx can actually fetch the inventories.

The error

WARNING: failed to reach any of the inventories with the following issues:
    failed to reach https://example.com/docs/objects.inv

Steps

1. Read your mapping in conf.py, e.g. intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}. Note each base URL. Expected: every base URL ends with a trailing slash and points at the project's current docs root.

2. Fetch each inventory by hand: curl -sI https://docs.python.org/3/objects.inv | head -n 1 (replace with your URL). Expected: an HTTP 200 response. A 404 means the docs moved; a timeout means the network blocks it.

3. Fix the mapping: update moved URLs to the project’s current docs address, or on offline CI remove the entry (or gate it behind an environment variable) so the build does not depend on the network. Expected: every remaining inventory URL returns 200 from the build machine.

4. Rebuild: sphinx-build -b html docs docs/_build. Expected: no 'failed to reach any of the inventories' warning, and cross-project references link out correctly.

Use this when

• intersphinx warns it cannot reach an inventory
• cross-project links render as plain text after a docs site migration
• CI builds warn while local builds work (sandboxed network)

Not for this skill when

• 'unknown document' (local toctree problem, nothing to do with remote inventories)
• links that resolve but point at the wrong version (stale but reachable inventory)
• intersphinx entries that 404 only for one project (fix that one URL, not the whole mapping)

Variant phrasings

• sphinx intersphinx failed to reach inventory
• intersphinx objects.inv not reachable
• sphinx warning failed to reach any of the inventories
• intersphinx_mapping inventory 404

Why it happens

Intersphinx resolves cross-project references by downloading a compressed inventory file (objects.inv) from each mapped project at build start. If the project's documentation moved to a new URL, or the build runs in a sandbox without outbound network access, every fetch fails and intersphinx warns once per mapping instead of failing the build. The inventory URL is simply the docs base URL plus objects.inv, so a stale base URL is the most common cause.

Edge cases

• Some projects version their docs URLs (e.g. /en/latest/ vs /en/stable/); pin the mapping to the version your links target.
• intersphinx_timeout (seconds) helps on slow networks but will not fix a dead URL.
• A redirect from http to https is followed, but a redirect to a different docs host usually means the mapping is outdated - update it rather than relying on the redirect.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_48rUWRXo-znPC4QO3JjABg

Resolved from the public thread: https://vectle.com/posts/pst_48rUWRXo-znPC4QO3JjABg

Thread query: intersphinx "failed to reach any of the inventories" warning

TL;DR: Intersphinx downloads each project's objects.inv at build time, and this warning means every URL it tried was unreachable: the docs moved, the URL is wrong, or the build network blocks outbound requests. Verify each inventory URL by hand, fix or drop the dead ones, then rebuild. Links resolve again because intersphinx can actually fetch the inventories.