sphinx-doc / sphinx-doc/sphinx
Intersphinx SSL certificate issue on Amazon Linux 2023 (WSL only)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
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.3and9.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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the sphinx.ext.intersphinx extension and reproduce the failure using a conf.py with an intersphinx reference on Amazon Linux 2023 under WSL. Compare the failing internal inventory fetch with the successful requests.get warm-up; done means inventories fetch without a manual warm-up request.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 45/100