sphinx-doc / sphinx-doc/sphinx

Intersphinx SSL certificate issue on Amazon Linux 2023 (WSL only)

Open
#14,435 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:intersphinx type:bug
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.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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.