[intersphinx] `'<' not supported between instances of 'dict' and 'dict'` in incremental builds

[pmatulis]

Describe the bug

I've been using the intersphinx extension for a while with good results. However, the remote resource started using different release codenames such that what used to be words are now decimal numbers.

How to Reproduce

URL components:

before: zed now: 2023.1

My conf.py now looks like this:

intersphinx_mapping = {
     'cdg': ('https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/2023.1', None)
  }

When I build my doc set I now get this error:

loading intersphinx inventory from https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/2023.1/objects.inv...

Extension error (sphinx.ext.intersphinx):
Handler <function load_mappings at 0x7f9ecd08acb0> for event 'builder-inited' threw an exception (exception: '<' not supported between instances of 'dict' and 'dict')
ERROR: InvocationError for command /home/ubuntu/git/openstack-guides/charm-guide/.tox/docs/bin/sphinx-build -j auto -W -d doc/build/doctrees -b html doc/source doc/build/html (exited with code 2)

I can download the objects.inv file and inspect it with no issues:

wget https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/2023.1/objects.inv

python3 -m sphinx.ext.intersphinx objects.inv
std:doc
        configure-openstack                      Configure OpenStack                     : configure-openstack.html
        index                                    OpenStack Charms Deployment Guide       : index.html
        install-juju                             Install Juju                            : install-juju.html
        install-maas                             Install MAAS                            : install-maas.html
        install-openstack                        Install OpenStack                       : install-openstack.html
        install-openstack-juju-status            OpenStack cloud                         : install-openstack-juju-status.html
std:label
        genindex                                 Index                                   : genindex.html
        install_maas                             Install MAAS                            : install-maas.html#id1
        install_openstack_juju_status            OpenStack cloud                         : install-openstack-juju-status.html#install-openstack-juju-status
        modindex                                 Module Index                            : py-modindex.html
        neutron_networking                       Neutron networking                      : install-openstack.html#neutron-networking
        ovs_bridge                               Create OVS bridge                       : install-maas.html#ovs-bridge
        public_networking                        Set up public networking                : configure-openstack.html#public-networking
        py-modindex                              Python Module Index                     : py-modindex.html
        search                                   Search Page                             : search.html
        tag_nodes                                Tag nodes                               : install-maas.html#tag-nodes
        test_openstack                           Final results and dashboard access      : install-openstack.html#test-openstack

Environment Information

Platform:              linux; (Linux-5.19.0-1024-aws-x86_64-with-glibc2.35)
Python version:        3.10.6 (main, May 29 2023, 11:10:38) [GCC 11.3.0])
Python implementation: CPython
Sphinx version:        7.0.1
Docutils version:      0.20.1
Jinja2 version:        3.1.2
Pygments version:      2.15.1

Sphinx extensions

No response

Additional context

No response

[picnixz]

It's a bit weird, but I don't have the issue on my side. Maybe you have an old inventory that was cached ? try to run the command with -E so that you wipe the output directory.

[picnixz]

@pmatulis Is the issue still persisting?

[picnixz]

I assume that the issue was caused by a cached inventory. If two inventories are the same but one has a different name, maybe the issue will appear again. I think wiping out the build folder would solve the issue but it's possible that we do have an issue (I'll investigate more upon next month since it requires quite a setup to detect this).

[papoteur-mga]

Hello, I get a similar error while building documentation for sphinx_notfound_page 1.0.0 using sphinx 7.2.5

Extension error (autoapi.extension):
Handler <function run_autoapi at 0x7f434b9b37f0> for event 'builder-inited' threw an exception (exception: '<' not supported between instances of 'str' and 'int')

I found this report by googling. Thus the cause could be outside.

[picnixz]

@papoteur-mga Thank you for the report.

I think your issue is a bit different since the failure occurs in run_autoapi which is part of the autoapi extension and not in load_mappings which is part of sphinx.ext.intersphinx. Also the bad types are the not same (so the objects being compared are likely not the same neither).

For the OP's issue, it was likely something that occurred due to some serialized information (at least according to what the function does).

[andrei-korshikov]

try to run the command with -E so that you wipe the output directory.

Just for your information. I had the same error message as OP:

Running Sphinx v7.2.6
loading pickled environment... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://requests.readthedocs.io/en/latest/objects.inv...

Extension error (sphinx.ext.intersphinx):
Handler <function load_mappings at 0x7fe0dfc40ea0> for event 'builder-inited' threw an exception (exception: '<' not supported between instances of 'dict' and 'dict')

The solution was to delete the file .doctrees/environment.pickle or use -E option for sphinx-build. So I do agree that "the issue was caused by a cached inventory."

The issue arouse after I didn't touch a project for a while (in my case about a month). And as far as I can tell it is not related to decimal numbers in URL.

[pmatulis]

@andrei-korshikov Thanks for this. I'll try it the next time the issue crops up again.

Is there a way for the software to prevent this scenario from occurring?

[picnixz]

I don't know exactly where the issue is coming from actually, namely I don't know if the issue is because there are two versions of an inventory that are being compared (and merged/updated) or if it's something else.

I don't have time to investigate until November but anyone who wants to help can first check where the error is coming from, e.g., by creating two inventories (just create a separate project and make its docs, you'll get an inventory for this). Also, it might be the case that one (remote) inventory was created using an older version of sphinx and when you update your project, a new (remote) inventory is there, possibly with a different structure, hence the exception. AFAIK, we don't have a way to prevent this error (but I may be wrong).

@pmatulis Can you update the title of your issue since we could confirm that the issue is a serialization issue and impacts more than what was originally assumed? like "sphinx.ext.intersphinx.load_mappings fails when encountering incompatible cached inventories" or something like that.

[adamchainz]

Getting the same on a project that I’m upgrading the Django version on:

@@ -84,14 +84,14 @@
 intersphinx_mapping = {
     "python": (
         "https://docs.python.org/3/",
         "https://docs.python.org/3/objects.inv",
     ),
     "django": (
-        "https://docs.djangoproject.com/en/4.0/",
-        "https://docs.djangoproject.com/en/4.0/_objects/",
+        "https://docs.djangoproject.com/en/5.0/",
+        "https://docs.djangoproject.com/en/5.0/_objects/",
     ),
 }
 
 
 # -- Options for HTML output -------------------------------------------------
 # affects ePub which is based on HTML

Same message:

$ make latexpdf
Running Sphinx v7.2.6
Initializing Spelling Checker 8.0.0
loading pickled environment... done
loading intersphinx inventory from https://docs.djangoproject.com/en/5.0/_objects/...

Extension error (sphinx.ext.intersphinx):
Handler <function load_mappings at 0x113990360> for event 'builder-inited' threw an exception (exception: '<' not supported between instances of 'dict' and 'dict')
make: *** [latexpdf] Error 1

Removing the cache with rm _build/doctrees/environment.pickle fixed the issue.

[picnixz]

Ah thank you for reminding me that I should have said that I now know where exactly was the issue (see the related PR).

I stumbled upon another interrogation on how to to fix the issue and so my PR is currently stalled.

So for people who also have this issue, don't worry we technically have a fix and know what causes the issue.

By the way, the issue occurs independently of whether there are numbers or not in the url. It only arises because the URL for the project is changed.

I have a bit of time in a few hours so I'll try fixing the fix.

[papoteur-mga]

@papoteur-mga Thank you for the report.

I think your issue is a bit different since the failure occurs in run_autoapi which is part of the autoapi extension and not in load_mappings which is part of sphinx.ext.intersphinx. Also the bad types are the not same (so the objects being compared are likely not the same neither).

Thanks, I fixed my build problem by using sphinx-autoapi in version 3.0.0

[jastich]

I see the same error as @pmatulis when using the following:

CPython 3.12.0

Jinja2                        3.1.2
docutils                      0.18.1
Pygments                      2.17.2
Sphinx                        7.2.6
sphinx-rtd-theme              1.3.0
sphinxcontrib-applehelp       1.0.7
sphinxcontrib-devhelp         1.0.5
sphinxcontrib-htmlhelp        2.0.4
sphinxcontrib-jquery          4.1
sphinxcontrib-jsmath          1.0.1
sphinxcontrib-qthelp          1.0.6
sphinxcontrib-serializinghtml 1.1.9

Output:

Running Sphinx v7.2.6
loading pickled environment... done
loading intersphinx inventory from http://localhost/pkgname/1.1.0.dev20231127202836+93b9f58/objects.inv...

Extension error (sphinx.ext.intersphinx):
Handler <function load_mappings at 0x7f6c507363e0> for event 'builder-inited' threw an exception (exception: '<' not supported between instances of 'dict' and 'dict')

[jastich]

Seems to be an issue with the content of objects.inv and not its retrieval. I get the same error if I use the file locally on disk.

[picnixz]

Ok, I think I never explained it properly but here's a way to fix the issue for now:

• Run sphinx using -E option or manually delete the content of the build directory (i.e., do a full rebuild). The only reason why there is this issue is when the structure of the remote inventory is changed for some reason. The reason why people never encountered that error is because the call to sorted actually never happened !

As I said previously, I won't work on anything before February (I know that issues are stacking up but I have really no time at all).

[Borda]

seems we have the sam issue but somehow this appears with REadTheDocs only on the main branch not when we build as a PR preview... https://readthedocs.org/projects/lit-utilities/builds/23862270/

[picnixz]

As I said, it's definitely a cache issue (the sorted call only occurs when you have are using a cache whose intersphinx mapping is different). RTD appears to run twice the build and they are possibly changing the mapping in between the runs (I don't know). The issue is with 6.2.x and not when Sphinx 5.3 is being used apparently.

@humitos Do you know about this one?

[humitos]

@picnixz Hi 👋🏼 . Read the Docs is not doing anything in between those commands. So, I'm not sure what could be happening here.

@Borda are you experiencing this issue locally if you run the same set of commands than on Read the Docs?

It would be good to have an isolated repository that reproduce this issue to be able to debug it further.

[Borda]

are you experiencing this issue locally if you run the same set of commands than on Read the Docs?

No, canot reproduce it locally, and also downgrade from 6.2 to 5.3 resolved the issue