intersphinx "failed to reach any of the inventories" warning

TL;DR

The warning means Sphinx tried to download every remote inventory file (objects.inv) listed in intersphinx_mapping and every download failed, so all cross-project links in this build are dead. It is a fetch problem, not a link problem. Fix: find out which URL failed and why (run the build verbose), then fix the network, the URL, the TLS verification, or the timeout. As a fast workaround, download the inventory once and point the mapping at the local file.

The exact error

In the Sphinx build log:

WARNING: failed to reach any of the inventories with the following issues:

Sometimes followed by per-URL lines naming each failed inventory. The build continues, but every intersphinx cross-reference (:py:class:, :ref:, and friends pointing at the remote project) renders as plain text instead of a link.

Steps

1. Rebuild verbose to see which URL failed and why.

sphinx-build -b html -v docs/ build/

Expected: a line like "loading intersphinx inventory from [URL]/objects.inv" followed by the concrete failure (connection refused, certificate verify failed, 404, read timed out). Without -v you only see the aggregate warning.

1. Check reachability from the same machine that runs the build.

curl -sI [URL]/objects.inv

Expected: HTTP 200. If this fails, the fix is environmental, not Sphinx config: the build machine has no network route, needs a proxy, or sits behind a firewall. CI sandboxes with egress disabled hit this constantly.

1. If curl works but Sphinx fails with a certificate error, the build's TLS verification is rejecting the remote's certificate (corporate MITM proxy or an expired cert).

# conf.py: trust the environment's CA bundle, or as a last resort
tls_verify = False

Expected: the inventory loads. Only set tls_verify to False for inventories you trust, over networks you control; otherwise install the right CA certificates so verification passes honestly.

1. If the failure is a 404, the remote docs moved. Open the base URL in a browser and update the mapping to the canonical location.

# conf.py
intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
}

Expected: the inventory URL resolves again. Remote projects reorganize their docs; stale base URLs are the most common cause of a sudden appearance of this warning on a previously green build.

1. If the failure is a timeout on a slow remote, raise the fetch timeout.

# conf.py
intersphinx_timeout = 30

Expected: slow inventories finish downloading instead of being skipped. The default is short; big inventories over slow links need more.

1. For fully offline builds, stop fetching entirely: download each inventory once and reference the local files.

# conf.py
intersphinx_mapping = {
    'python': ('https://docs.python.org/3', 'inventories/python-objects.inv'),
}

Expected: zero network fetches, no warning. Refresh the local copies when the remote project releases.

How to confirm it worked

Rebuild and grep the log: the "failed to reach any of the inventories" warning is gone, and verbose output shows "loading intersphinx inventory from ..." succeeding for each project. Then spot-check one cross-project link in the rendered HTML.

When to use

Use this when a Sphinx build logs "failed to reach any of the inventories" and cross-project references are not linking. Use it in CI or containerized doc builds, where network and TLS environments differ from your laptop.

When NOT to use

Do not use this when inventories load fine but specific links still fail; that is a missing-object or wrong-target problem, not a fetch problem. Do not use it if your project has no intersphinx_mapping at all; then the warning cannot come from intersphinx. Do not use it for "inventory has no object named" style warnings, which mean the fetch worked.

Variant phrasings this covers

• "WARNING: failed to reach any of the inventories with the following issues"
• sphinx intersphinx inventory download failed
• intersphinx objects.inv 404 / certificate verify failed / read timed out
• cross-project sphinx links broken after moving CI to offline builds

Root cause

intersphinx resolves cross-project links at build time by downloading each remote project's objects.inv. The warning aggregates all fetch failures into one message, which is why it gives no per-URL detail unless you build verbose. Every listed cause (no network, TLS rejection, moved docs, timeout, offline build) is a failure to fetch the same small file; the fix is always to restore the fetch or stop requiring it.

Edge cases

• A remote behind Cloudflare or a bot wall may return 403 to Sphinx's fetcher while loading fine in a browser; treat as a stale or unfetchable URL and pin a local copy.
• Mixed schemes (http inventory URL on a machine that only allows https egress) fail silently into this warning; check the URL scheme.
• Sphinx caches nothing here: every build re-fetches, so a flaky remote produces a flaky warning.
• If only SOME inventories fail, the warning still appears; fix per URL.