sphinx-doc
ExtensionError (sphinx.ext.intersphinx._load) : exception: not enough arguments for format string
Describe the bug
When the intersphinx inventory is reached through a SSL-aware HTTP proxy (standard in company networks), there might be a redirect happening. This redirect seems to trigger a bug in the intersphinx._load code
loading intersphinx inventory 'python' from https://docs.python.org/3/objects.inv ...
intersphinx inventory has moved: https://docs.python.org/3/objects.inv -> https://<private.proxyhost.net>:<port>/<path>?origurl=https%3A%2F%2Fdocs.python.org%2F3%2Fobjects.inv&<other parameters>
Extension error (sphinx.ext.intersphinx._load)!
Versions
========
* Platform: win32; (Windows-11-10.0.22631-SP0)
* Python version: 3.12.11 (CPython)
* Sphinx version: 8.2.3
* Docutils version: 0.21.2
* Jinja2 version: 3.1.6
* Pygments version: 2.19.2
Last Messages
=============
None.
Loaded Extensions
=================
None.
Traceback
=========
File "C:\_dev\python_ws\16_vne\python-dq4ts-lib\.nox\doc\Lib\site-packages\sphinx\events.py", line 415, in emit
raise ExtensionError(
sphinx.errors.ExtensionError: Handler <function load_mappings at 0x000001A834D14720> for event 'builder-inited' threw an exception (exception: not enough arguments for format string)
How to Reproduce
Simply run sphinx with at least one intersphinx link (for example documenting a class that extends stdlib str, or referencing :class:str in one of the rst documents)
Environment Information
Platform: win32; (Windows-11-10.0.22631-SP0)
Python version: 3.12.11 (main, Sep 18 2025, 19:45:51) [MSC v.1944 64 bit (AMD64)])
Python implementation: CPython
Sphinx version: 8.2.3
Docutils version: 0.21.2
Jinja2 version: 3.1.6
Pygments version: 2.19.2
Sphinx extensions
`sphinx.ext.intersphinx`
Additional context
No response
Full traceback :
Traceback (most recent call last):
File "C:\<path>\.nox\doc\Lib\site-packages\sphinx\events.py", line 404, in emit
results.append(listener.handler(self.app, *args))
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\<path>\.nox\doc\Lib\site-packages\sphinx\ext\intersphinx\_load.py", line 187, in load_mappings
updated = [f.result() for f in concurrent.futures.as_completed(futures)]
^^^^^^^^^^
File "C:\Users\<user>\AppData\Roaming\uv\python\cpython-3.12.11-windows-x86_64-none\Lib\concurrent\futures\_base.py", line 449, in result
return self.__get_result()
^^^^^^^^^^^^^^^^^^^
File "C:\Users\<user>\AppData\Roaming\uv\python\cpython-3.12.11-windows-x86_64-none\Lib\concurrent\futures\_base.py", line 401, in __get_result
raise self._exception
File "C:\Users\<user>\AppData\Roaming\uv\python\cpython-3.12.11-windows-x86_64-none\Lib\concurrent\futures\thread.py", line 59, in run
result = self.fn(*self.args, **self.kwargs)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\<path>\.nox\doc\Lib\site-packages\sphinx\ext\intersphinx\_load.py", line 294, in _fetch_inventory_group
issues = '\n'.join(f[0] % f[1:] for f in failures)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\<path>\.nox\doc\Lib\site-packages\sphinx\ext\intersphinx\_load.py", line 294, in <genexpr>
issues = '\n'.join(f[0] % f[1:] for f in failures)
~~~~~^~~~~~~
TypeError: not enough arguments for format string
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
File "C:\<path>\.nox\doc\Lib\site-packages\sphinx\cmd\build.py", line 414, in build_main
app = Sphinx(
^^^^^^^
File "C:\<path>\.nox\doc\Lib\site-packages\sphinx\application.py", line 332, in __init__
self._init_builder()
File "C:\<path>\.nox\doc\Lib\site-packages\sphinx\application.py", line 414, in _init_builder
self.events.emit('builder-inited')
File "C:\<path>\.nox\doc\Lib\site-packages\sphinx\events.py", line 415, in emit
raise ExtensionError(
sphinx.errors.ExtensionError: Handler <function load_mappings at 0x000001A834D14720> for event 'builder-inited' threw an exception (exception: not enough arguments for format string)
I ran into the same error while running sphinx under my company's proxy.
Run command: python -m sphinx build C:\Users\...\doc C:\Users\...\site -a -E -j auto
Running Sphinx v8.2.3
loading translations [en]... done
making output directory... done
loading intersphinx inventory 'numpy' from https://numpy.org/doc/stable/objects.inv ...
WARNING: failed to reach any of the inventories with the following issues:
intersphinx inventory 'https://numpy.org/doc/stable/objects.inv' not fetchable due to <class 'requests.exceptions.HTTPError'>: 403 Client Error: Forbidden for url: https://numpy.org/doc/stable/objects.inv
Extension error (sphinx.ext.intersphinx._load)!
Versions
========
* Platform: win32; (Windows-10-10.0.22631-SP0)
* Python version: 3.11.9 (CPython)
* Sphinx version: 8.2.3
* Docutils version: 0.20.1
* Jinja2 version: 3.1.6
* Pygments version: 2.19.2
Last Messages
=============
None.
Loaded Extensions
=================
None.
Traceback
=========
File "C:\Users\...\Lib\site-packages\sphinx\events.py", line 415, in emit
raise ExtensionError(
sphinx.errors.ExtensionError: Handler <function load_mappings at 0x000001617A72CAE0> for event 'builder-inited' threw an exception (exception: not enough arguments for format string)
Update:
Found the issue, here's what failures looks like for me :
[('unknown or unsupported inventory version: ValueError(\'invalid inventory header: <!--samlchecks_get.html --><!DOCTYPE html><html> ... (very long html file) ... ,)] i.e a 1-element list which element is a 1-element tuple.
File "C:\<path>\.nox\doc\Lib\site-packages\sphinx\ext\intersphinx\_load.py", line 294, in <genexpr> issues = '\n'.join(f[0] % f[1:] for f in failures)
expects tuples with at least 2 elements, which causes the error
I'm creating a PR to replace line 294 with
issues = '\n'.join(
f[0] % f[1:] if len(f) > 1 and '%' in f[0] else ' -'.join(f for f in f)
for f in failures
)