Describe the bug
My problem is that intersphinx fails to download inventories due to an SSL error in some environments.
The error message reads:
WARNING: failed to reach any of the inventories with the following issues:
intersphinx inventory 'https://docs.python.org/3/objects.inv' not fetchable due to <class 'requests.exceptions.SSLError'>: HTTPSConnectionPool(host='docs.python.org', port=443): Max retries exceeded with url: /3/objects.inv (Caused by SSLError(SSLError(0, 'unknown error (_ssl.c:3108)')))
(it appears for ALL of the inventories with the same error message)
Environment
- OS: Amazon Linux 2023 - The issue occurs on Amazon Linux 2023 running inside WSL, but does not occur on AWS-hosted Amazon Linux 2023 instances.
- Sphinx: tested with both:
8.2.3 and 9.0.4
- Network restrictions: none
- No custom SSL verification or CA configuration is present in
conf.py
- The issue reproduces consistently
Installed dependencies
dependencies = [
"certifi>=2025.11.12",
"myst-parser>=4.0.1",
"sphinx-markdown-builder>=0.6.8",
"sphinx-rtd-theme>=3.0.2",
"sphinx~=8.2.3",
"sphinxcontrib-confluencebuilder>=2.15.0",
"sphinxcontrib-mermaid>=1.0.0",
"sphinxcontrib-napoleon>=0.7",
"sphinx-autoapi>=3.6.1",
]
The SSL failures happens only when intersphinx performs the request internally.
As a workaround, adding the following line to my conf.py consistently resolves the issue:
import requests
requests.get("https://docs.python.org/3/objects.inv")
After this request has been executed once, intersphinx works normally. Not just for the test URL but for ALL intersphinx URLs!
Expected
intersphinx should be able to fetch inventories without requiring a manual warm-up request through requests.
How to Reproduce
Any conf.py with an intersphinx reference seems to trigger the error.
Environment Information
Platform: linux; (Linux-6.6.114.1-microsoft-standard-WSL2-x86_64-with-glibc2.34)
Python version: 3.11.13 (main, Oct 7 2025, 15:34:32) [Clang 20.1.4 ])
Python implementation: CPython
Sphinx version: 9.0.4
Docutils version: 0.22.4
Jinja2 version: 3.1.6
Pygments version: 2.20.0
Sphinx extensions
extensions = [ 'autoapi.extension', 'autoapi_prefix', 'content_table', 'myst_parser', 'sphinx.ext.autodoc.typehints', 'sphinx.ext.autosectionlabel', 'sphinx.ext.extlinks', 'sphinx.ext.graphviz', 'sphinx.ext.inheritance_diagram', 'sphinx.ext.intersphinx', 'sphinx.ext.napoleon', 'sphinx.ext.todo', 'sphinx.ext.viewcode', # 'sphinx_diagrams', 'sphinx_markdown_builder', 'sphinx_rtd_theme', 'sphinxcontrib.confluencebuilder', 'sphinxcontrib.mermaid', ]
Additional context
requests==2.32.2
requests-file==3.0.1
requests-oauthlib==2.0.0
requests-toolbelt==1.0.0
Describe the bug
My problem is that
intersphinxfails to download inventories due to an SSL error in some environments.The error message reads:
(it appears for ALL of the inventories with the same error message)
Environment
8.2.3and9.0.4conf.pyInstalled dependencies
The SSL failures happens only when
intersphinxperforms the request internally.As a workaround, adding the following line to my
conf.pyconsistently resolves the issue:After this request has been executed once,
intersphinxworks normally. Not just for the test URL but for ALL intersphinx URLs!Expected
intersphinxshould be able to fetch inventories without requiring a manual warm-up request throughrequests.How to Reproduce
Any conf.py with an intersphinx reference seems to trigger the error.
Environment Information
Sphinx extensions
Additional context
requests==2.32.2
requests-file==3.0.1
requests-oauthlib==2.0.0
requests-toolbelt==1.0.0