Skip to content

Parallel build fails with sphinx-argparse v0.6.0 #98

Closed
#99
qgis-deployment/qgis-deployment-toolbelt-cli
#868
Closed
Parallel build fails with sphinx-argparse v0.6.0#98
#99
qgis-deployment/qgis-deployment-toolbelt-cli
#868

Description

@loichuder
loichuder
opened on Jul 2, 2026

Since the v0.6.0 release of sphinx-argparse, our Sphinx builds launched in parallel (-j auto) fail with the following error:

Traceback
=========
      File ".../python3.12/site-packages/sphinx/util/parallel.py", line 126, in terminate
        self._result_funcs.pop(tid)
    KeyError: 0

This is clearly related to sphinx-argparse since the error disappears when the extension is not loaded in Sphinx.

I attach a ZIP containing a basic repo to reproduce the error: sphinx_parallel.zip

Running sphinx-build -j auto doc _build in the repo root produces the aforementioned error. Commenting the extensions = ["sphinxarg.ext"] in conf.py or using -j 1 makes the error disappear.

Version info

Versions
========

* Platform:         linux; (Linux-6.8.0-124-generic-x86_64-with-glibc2.39)
* Python version:   3.12.3 (CPython)
* Sphinx version:   9.1.0
* Docutils version: 0.22.4
* Jinja2 version:   3.1.6
* Pygments version: 2.20.0

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

* sphinx.ext.mathjax (9.1.0)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* sphinx.ext.autodoc (9.1.0)
* sphinxarg.ext (0.6.0)

Activity

  1. jontwo commented on Jul 9, 2026

    @jontwo
    jontwo
    on Jul 9, 2026

    I opened the duplicate issue above and forgot to mention that when the tool crashes, it hangs and has to be manually cancelled (ctrl-c or CI timeout). CI log show below - check the timestamps.

    2026-07-07T15:23:40.183797Z 01E Traceback
2026-07-07T15:23:40.183798Z 01E =========
2026-07-07T15:23:40.183798Z 01E 
2026-07-07T15:23:40.183799Z 01E       File "/builds/jbariskmanagement/code/farmmap/.venv/lib/python3.12/site-packages/sphinx/util/parallel.py", line 126, in terminate
2026-07-07T15:23:40.183800Z 01E         self._result_funcs.pop(tid)
2026-07-07T15:23:40.183801Z 01E     KeyError: 3
2026-07-07T15:23:40.183955Z 01E 
2026-07-07T15:23:40.183999Z 01E 
2026-07-07T15:23:40.187295Z 01E The full traceback has been saved in:
2026-07-07T15:23:40.187300Z 01E /tmp/sphinx-err-cw1a73xt.log
2026-07-07T15:23:40.187365Z 01E 
2026-07-07T15:23:40.187367Z 01E To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
2026-07-07T15:23:40.187368Z 01E Please also report this if it was a user error, so that a better error message can be provided next time.
2026-07-07T16:22:55.041380Z 00O section_end:1783441375:step_script
2026-07-07T16:22:55.041386Z 00O+�[0K�[0;33mWARNING: step_script could not run to completion because the timeout was exceeded. For more control over job and script timeouts see: https://docs.gitlab.com/ci/runners/configure_runners/#set-script-and-after_script-timeouts�[0;m
2026-07-07T16:22:55.763048Z 00O �[31;1mERROR: Job failed: execution took longer than 1h0m0s seconds�[0;m

    Should this be opened as a separate issue and if so, where?

  2. kevinoid
    added 2 commits that reference this issue on Jul 16, 2026

    build(docs): disable parallel Sphinx builds

    e6c686d

    build(docs): disable parallel Sphinx builds

    75e7aaf

  3. Guts commented on Jul 27, 2026

    @Guts
    Guts
    on Jul 27, 2026

    I'm facing the same issue: https://github.com/qgis-deployment/qgis-deployment-toolbelt-cli/actions/runs/30259236103/job/89954970271. I found out that PR fixes it: #99

    @RobertoRoos or @AA-Turner or any maintainer, is it possible to review it please?

  4. Guts
    added 5 commits that reference this issue on Jul 27, 2026

    fix(ci): disable sphinx parallel build since 'sphinx-argparse' is not…

    e39bf1c

    fix(docs): pin sphinx-argprase to <0.6.0 waiting for parallelism fix

    513a64c

    fix(docs): pin sphinx-argprase to <0.6.0 waiting for parallelism fix

    fa74b9e

    fix(docs): pin sphinx-argparse to <0.6.0 and use Python 3.12 to fix d…

    c31f22e

    fix(docs): disable parallel build because of upstream issue (#423)

    ed4410d

  5. RobertoRoos commented on Aug 19, 2026

    @RobertoRoos
    RobertoRoos
    on Aug 19, 2026
    Collaborator

    I'm finally finding this, sorry it took to long. #99 looks good, I'll try to get it merged soon.

  6. RobertoRoos
    closed this as completedin #99on Aug 19, 2026

  7. RobertoRoos commented on Aug 19, 2026

    @RobertoRoos
    RobertoRoos
    on Aug 19, 2026
    Collaborator

    @Guts I cannot find the commit belonging to your linked failing job, so I cannot check if the tip of main fixes the problem.

    Are you in a position to test our main? Then I can confidently tag a minor release immediately.

  8. Guts commented on Aug 19, 2026

    @Guts
    Guts
    on Aug 19, 2026

    @Guts I cannot find the commit belonging to your linked failing job, so I cannot check if the tip of main fixes the problem.

    Are you in a position to test our main? Then I can confidently tag a minor release immediately.

    Hello,

    I van give it a tomorrow.

  9. Guts commented on Aug 21, 2026

    @Guts
    Guts
    on Aug 21, 2026

    I've just tested it on a local clone of https://github.com/qgis-deployment/qgis-deployment-toolbelt-cli/:

    pip install -e .[doc]
pip install git+https://github.com/sphinx-doc/sphinx-argparse.git
sphinx-build -b html -d docs/_build/cache -j auto -q docs docs/_build/html

    And it works 🥳 !

  10. RobertoRoos commented on Aug 21, 2026

    @RobertoRoos
    RobertoRoos
    on Aug 21, 2026
    Collaborator

    Great, thanks for letting us know. I just released v0.6.1, I hope CI builds will now work as expected.

  11. kevinoid
    added a commit that references this issue on Aug 21, 2026

    build(docs): re-enable parallel Sphinx builds

    6861bc2
  12. inmantaci
    added 2 commits that reference this issue on Aug 21, 2026

    Bump sphinx-argparse from 0.6.0 to 0.6.1 (PR #10736)

    82f804c

    Bump sphinx-argparse from 0.6.0 to 0.6.1 (PR #10737)

    f6f5182
  13. reuterbal
    added a commit that references this issue on Oct 22, 2026

    chore(deps-dev): update sphinx-argparse requirement from <0.5 to <0.7 (…

    8b74284
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions