Skip to content

intersphinx: Stringify error arguments in _display_failures#14414

Open
cobaltt7 wants to merge 2 commits intosphinx-doc:masterfrom
cobaltt7:stringify-errors-intersphinx
Open

intersphinx: Stringify error arguments in _display_failures#14414
cobaltt7 wants to merge 2 commits intosphinx-doc:masterfrom
cobaltt7:stringify-errors-intersphinx

Conversation

@cobaltt7
Copy link
Copy Markdown

@cobaltt7 cobaltt7 commented Apr 24, 2026

Purpose

I got this error when running sphinx-build:

    Traceback (most recent call last):
      File "...\black\.venv\Lib\site-packages\sphinx\ext\intersphinx\_load.py", line 235, in _display_failures
        formatted.append(failure_args[0] % failure_args[1:])
                         ~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for %: 'int' and 'tuple'

It looks like something threw this error:

OSError: [Errno 22] Invalid argument: '...\\black\\docs\\_build\\.doctrees\\__intersphinx_cache__\\<name>_objects.inv'

And err.args was (22, "Invalid argument"). When it was passed to _display_failures, it failed to generate a proper error string.
I'm still investigating the cause of the OSError, but for now1 Sphinx should be fixed to propagate the error message properly.

I didn't add a changelog entry because it's still the 9.1.0 changelog - should I be the one to update it, or should I wait for someone else?

Docutils 0.22 on py312 and ty typecheck were both failing on main already.
Docutils failure on py315 doesn't seem to be my fault either - it's fixed in #14399

References

https://github.com/psf/black/actions/runs/22561832229/job/65349935011 - CI log that first alerted me to the error

Full traceback
Versions
========

* Platform:         win32; (Windows-11-10.0.26200-SP0)
* Python version:   3.12.4 (CPython)
* Sphinx version:   9.1.0
* Docutils version: 0.22.4
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============

None.

Loaded Extensions
=================

None.

Traceback
=========

    Traceback (most recent call last):
      File "...\black\.venv\Lib\site-packages\sphinx\ext\intersphinx\_load.py", line 235, in _display_failures
        formatted.append(failure_args[0] % failure_args[1:])
                         ~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for %: 'int' and 'tuple'

    During handling of the above exception, another exception occurred:

    Traceback (most recent call last):
      File "...\black\.venv\Lib\site-packages\sphinx\events.py", line 441, in emit
        results.append(listener.handler(self._app, *args))
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "...\black\.venv\Lib\site-packages\sphinx\ext\intersphinx\_load.py", line 191, in load_mappings
        updated = [f.result() for f in concurrent.futures.as_completed(futures)]
                   ^^^^^^^^^^
      File "C:\Program Files\Python312\Lib\concurrent\futures\_base.py", line 449, in result
        return self.__get_result()
               ^^^^^^^^^^^^^^^^^^^
      File "C:\Program Files\Python312\Lib\concurrent\futures\_base.py", line 401, in __get_result
        raise self._exception
      File "C:\Program Files\Python312\Lib\concurrent\futures\thread.py", line 58, in run
        result = self.fn(*self.args, **self.kwargs)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "...\black\.venv\Lib\site-packages\sphinx\ext\intersphinx\_load.py", line 333, in _fetch_inventory_group
        _display_failures(failures),
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "...\black\.venv\Lib\site-packages\sphinx\ext\intersphinx\_load.py", line 237, in _display_failures
        formatted.append(' - '.join(failure_args))
                         ^^^^^^^^^^^^^^^^^^^^^^^^
    TypeError: sequence item 0: expected str instance, int found

    The above exception was the direct cause of the following exception:

    Traceback (most recent call last):
      File "...\black\.venv\Lib\site-packages\sphinx\cmd\build.py", line 414, in build_main
        app = Sphinx(
              ^^^^^^^
      File "...\black\.venv\Lib\site-packages\sphinx\application.py", line 340, in __init__
        self._init_builder()
      File "...\black\.venv\Lib\site-packages\sphinx\application.py", line 430, in _init_builder
        self.events.emit('builder-inited')
      File "...\black\.venv\Lib\site-packages\sphinx\events.py", line 452, in emit
        raise ExtensionError(
    sphinx.errors.ExtensionError: Handler <function load_mappings at 0x00000192CA9C8860> for event 'builder-inited' threw an exception (exception: sequence item 0: expected str instance, int found)

Footnotes

  1. An intersphinx_mapping key had </> in it. When Sphinx tried to use it as part of a cache file name, it crashed on Windows, which doesn't allow them in file names. This is more user error than Sphinx's fault, but it should have a clearer error message.

Signed-off-by: cobalt <61329810+cobaltt7@users.noreply.github.com>
Signed-off-by: cobalt <61329810+cobaltt7@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant