Issues when using confluence-builder with sphinxcontrib-plantuml

[thoerdo]

Hi.

When using confluencebuilder I ran into an issued when combining with sphinxcontrib-plantuml and I can not find the issue myself. Any chance you might guide me where to look / how to fix?

Issue summary

PlantUML images are created, yet not uploaded to Confluence, so the resulting Confluence pages only show an error message "Unknown Attachment", where the images should be. When creating plain HTML pages instead of Confluence pages, everything works fine.

Minimal code setup for test

project-dir

• docs/
  • index.rst
  • conf.py
  • requirements.txt
• requirements.txt
• tox.ini

requirements.txt
tox

tox.ini

[tox]
envlist = html, confluence
skipsdist = false

[testenv:html]
deps =
    -r docs/requirements.txt
commands =
     sphinx-build -a -E -n -j auto -T -v -W --keep-going --color docs docs/_build/html{posargs}

[testenv:confluence]
deps =
    -r docs/requirements.txt
commands =
    sphinx-build -a -b confluence -E -n -j auto -T -v -W --keep-going --color docs docs/_build/confluence {posargs}

docs/index.rst

PlantUML Demo
===============

This is a demo for PlantUML.

.. plantuml::

    Alice -> Bob: Hi!
    Alice <- Bob: How are you?

docs/requirements.txt

sphinx
sphinxcontrib-confluencebuilder
sphinxcontrib-plantuml

conf.py

extensions = [
    # -- General extensions
    "sphinx.ext.duration",  # durations report at the end of  Sphinx build
    # -- Specific addons
    "sphinxcontrib.plantuml",   # support for PlantUML diagrams
    # -- Confluene specific extensions
    # If building "tox -e html"  ensure to comment out the following extensions
    "sphinxcontrib.confluencebuilder"
]

# -- Extensions options: Plant-UML -------------------------------------------
# PlantUML configuration
current_dir = os.path.dirname(os.path.abspath(__file__))
plantuml_jar_path = os.path.join(current_dir, "../plantuml.jar")

plantuml = 'java -jar ' + plantuml_jar_path # Path to PlantUML jar file
plantuml_output_format = 'png'  # Output format for PlantUML diagrams
plantuml_cache_path = "plantuml"

# -- Extensions options: ConfluenceBuilder -----------------------------------
confluence_server_url = <server_url>
confluence_space_key = <space_key>
confluence_parent_page = <parent_page>
confluence_publish_token = <personal access token>

confluence_publish = True
confluence_publish_debug = "all" 

--> Yes the PAT should not be directly in the conf.py file, but for testing it will do

Execution & results

HTML

Running tox -e html from CLI (confluencebuilder extension is comment out within conf.py)

In docs/_build/html/plantuml/ac/ac54ff83b1193e04582c7ec1040cc831dafcc20c.png the created UML image is available, and also copied to docs/_build/html/_images/ac54ff83b1193e04582c7ec1040cc831dafcc20c.png.

In the rendered HTML pages the created image is visible as expected, with source path: _images/plantuml-ac54ff83b1193e04582c7ec1040cc831dafcc20c.png

Confluence

Running tox -e confluence from CLI

In docs/_build/confluence/plantuml/ac/ac54ff83b1193e04582c7ec1040cc831dafcc20c.png the created UML image is available, and also copied to docs/_build/confluence/ac54ff83b1193e04582c7ec1040cc831dafcc20c.png.

BE AWARE: For some reason the image is not linked in the docs/_build/confluence/scb-manifest.json file, and maybe this is also the error here.

In the rendered Confluence pages the created image is properly linked as ac54ff83b1193e04582c7ec1040cc831dafcc20c.png file, yet the image is not uploaded to the Confluence page, so the page only shows an "Unknown attachment" error.

Machine data

Ubuntu WSL on Windows 11

Distributor ID: Ubuntu
Description:    Ubuntu 24.04.2 LTS
Release:        24.04
Codename:       noble

Python version

> python --version
Python 3.12.3

Java version

> java --version
openjdk 21.0.8 2025-07-15
OpenJDK Runtime Environment (build 21.0.8+9-Ubuntu-0ubuntu124.04.1)
OpenJDK 64-Bit Server VM (build 21.0.8+9-Ubuntu-0ubuntu124.04.1, mixed mode, sharing)

PlantUML version
1.2025.4

Python packages within root folder

>pip list

Package       Version
------------- -------
cachetools    6.1.0
cfgv          3.4.0
chardet       5.2.0
colorama      0.4.6
distlib       0.4.0
filelock      3.18.0
identify      2.6.12
nodeenv       1.9.1
packaging     25.0
pip           24.0
platformdirs  4.3.8
pluggy        1.6.0
pre_commit    4.2.0
pyproject-api 1.9.1
PyYAML        6.0.2
tox           4.28.3
virtualenv    20.32.0

Python packages within tox Confluence environment

Package                         Version
------------------------------- -----------
alabaster                       1.0.0
anyio                           4.10.0
babel                           2.17.0
build                           1.3.0
cachetools                      6.1.0
certifi                         2025.8.3
cffi                            1.17.1
cfgv                            3.4.0
chardet                         5.2.0
charset-normalizer              3.4.3
click                           8.2.1
colorama                        0.4.6
coverage                        7.10.3
cryptography                    45.0.6
distlib                         0.4.0
docutils                        0.21.2
epac                            0.0.32
filelock                        3.18.0
gitdb                           4.0.12
GitPython                       3.1.45
h11                             0.16.0
hatch                           1.14.1
hatchling                       1.27.0
httpcore                        1.0.9
httpx                           0.28.1
hyperlink                       21.0.0
identify                        2.6.13
idna                            3.10
imagesize                       1.4.1
iniconfig                       2.1.0
jaraco.classes                  3.4.0
jaraco.context                  6.0.1
jaraco.functools                4.2.1
jeepney                         0.9.0
Jinja2                          3.1.6
keyring                         25.6.0
markdown-it-py                  3.0.0
MarkupSafe                      3.0.2
mdit-py-plugins                 0.5.0
mdurl                           0.1.2
more-itertools                  10.7.0
myst-parser                     4.0.1
nodeenv                         1.9.1
packaging                       25.0
pathspec                        0.12.1
pexpect                         4.9.0
pip                             25.1.1
platformdirs                    4.3.8
pluggy                          1.6.0
pre_commit                      4.3.0
ptyprocess                      0.7.0
pycparser                       2.22
pygit2                          1.18.1
Pygments                        2.19.2
pyproject-api                   1.9.1
pyproject_hooks                 1.2.0
pytest                          8.4.1
pytest-cov                      6.2.1
python-git                      2018.2.1
PyYAML                          6.0.2
requests                        2.32.4
rich                            14.1.0
roman-numerals-py               3.1.0
SecretStorage                   3.3.3
Send2Trash                      1.8.3
shellingham                     1.5.4
smmap                           5.0.2
sniffio                         1.3.1
snowballstemmer                 3.0.1
Sphinx                          8.2.3
sphinx-autodoc-typehints        3.2.0
sphinx-rtd-theme                3.0.2
sphinxcontrib-applehelp         2.0.0
sphinxcontrib-confluencebuilder 2.14.0
sphinxcontrib-devhelp           2.0.0
sphinxcontrib-htmlhelp          2.1.0
sphinxcontrib-jquery            4.1
sphinxcontrib-jsmath            1.0.1
sphinxcontrib-plantuml          0.30
sphinxcontrib-qthelp            2.0.0
sphinxcontrib-serializinghtml   2.0.0
tomli_w                         1.2.0
tomlkit                         0.13.3
tox                             4.28.4
trove-classifiers               2025.8.6.13
typing_extensions               4.14.1
urllib3                         2.5.0
userpath                        1.9.2
uv                              0.8.10
virtualenv                      20.34.0
yamllint                        1.37.1
zstandard                       0.23.0.0.0
urllib3                         2.5.0

I have no clue where to look.
So please, if you have any idea, where I might start investigating / fixing the problem, that would really be helpful.

Thank you!

[jdknight]

Been playing with a couple of environments (Arch, Windows and WSL+Ubuntu) and have not been able to reproduce an issue with missing files (yet).

For some reason the image is not linked in the docs/_build/confluence/scb-manifest.json file, and maybe this is also the error here.

Thanks for mentioning this. If the attachment is not listed in this file means that the extension could not internally register the file into its asset manager (which in turn will not be processed for publishing). So, if it helps with the debugging process, publishing is not required to reveal the issue.

With verbose logs enabled, do you see an image node process log for the image?

[confluence] process image node: ...\plantuml-ac54ff83b1193e04582c7ec1040cc831dafcc20c.png

I'll try to make some tweaks to the extension to add more verbose logging in various locations and maybe you can try re-running to see if it reveals anything with asset management.

[jdknight]

Mind trying with this option set?

confluence_asset_force_standalone = True

[jdknight]

Or, if willing, try out a prospect/reworked asset manager implementation that might resolve this issue:

pip install git+https://github.com/sphinx-contrib/confluencebuilder.git@new-am-testing

[thoerdo]

Hi @jdknight,

thank you for the feedback and hints on how to proceed.

Regarding your comments:

1. Yes, is this mentioned line:
   [confluence] process image node: <my-project-path>/docs/_build/confluence/plantuml-ac54ff83b1193e04582c7ec1040cc831dafcc20c.png

2. I modified the minimal environment a little and made some progress.

project-dir

docs/
index.rst
plantuml_demo.rst
conf.py
requirements.txt
requirements.txt
tox.ini

docs/index.rst

PlantUML Demo
===============

.. toctree::
    :maxdepth: 2
    :caption: Contents:

    plantuml_demo

This is a demo for PlantUML.

.. plantuml::

    Alice -> Bob: Hi!
    Alice <- Bob: How are you?

doc/plantuml_demo.rst

Demo
====

This is another demo for PlantUML.

.. plantuml::

    Bob -> Eve: Hi!
    Eve <- Bob: How are you?

Result

1. Image in docs/index.rst is visible in Confluence
2. Image in docs/plant_uml.rst is not visible in Confluence, and I get the same error as mentioned before.

In the sphinx-build log I see:

[confluence] process image node: <my-project-path>/docs/_build/confluence/plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] process image node: <my-project-path>/docs/_build/confluence/plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
...
publishing assets... [ 50%] plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
publishing assets... [100%] objects.inv

So only the first image get's published, the second is ignored.

This corresponds to the scb-manifest.json, where only the first image is listed:

"attachments": [
        {
            "id": "plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png",
            "pageId": "index",
            "pageTitle": "PlantUML Demo_TMP",
            "mimeType": "image/png",
            "hash": {
                "sha256": "dc35236e1cb67c7d9483d3bf9f51e1614f9ee24226eeae3d3b3166dd064bbdf4"
            },
            "path": "plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png"
        },
        {
            "id": "objects.inv",
            "pageId": "index",
            "pageTitle": "PlantUML Demo_TMP",
            "mimeType": "application/octet-stream",
            "hash": {
                "sha256": "e7a6711977d5a4313a86b6388b4561bbd9110b5b577171681f7f7fe57459caa5"
            },
            "path": "objects.inv"
        }

Are you able to reproduce that?

[thoerdo]

Adding: confluence_asset_force_standalone = True to conf.py had no effect

[thoerdo]

Or, if willing, try out a prospect/reworked asset manager implementation that might resolve this issue:

pip install git+https://github.com/sphinx-contrib/confluencebuilder.git@new-am-testing

Tried out this new version, by modifying:

docs/requirements.txt

sphinx
sphinxcontrib-plantuml
git+https://github.com/sphinx-contrib/confluencebuilder.git@new-am-testing

Result is the same as above: Only image on the index.rst page get published, not the 2nd image.

The output is a little different than before:

[confluence] process image node: <my-project-path>/docs/_build/confluence/plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] setup attachment key (index): plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] process image node: <my-project-path>/docs/_build/confluence/plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
[confluence] setup attachment key (plantuml_demo): plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
...
publishing assets... [ 50%] plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
publishing assets... [100%] objects.inv

[jdknight]

Appreciate the testing and providing results.

Interesting to see in the newer code attachment keys being setup (setup attachment key), but only two assets are being published. With the newer code, can you confirm if scb-manifest.json is still only populated with two assets and not the expected three? (I know you showed the attachment manifest entries for the re-configuration run, but not sure if it was the same when acquiring the test branch)

Tweaked the branch a bit; I am curious to know what the "asset finalization" verbose logs state. Expecting to see content such as the following (what I locally see):

[confluence] pre-processing doctree (index) for assets...
[confluence] pre-processing doctree (plantuml_demo) for assets...
[confluence] process image node: <WORKDIR>/plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] setup attachment key (index): plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] process image node: <WORKDIR>/plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
[confluence] setup attachment key (plantuml_demo): plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
...
[confluence] finalize assets (total: 3)...
[confluence] > plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png (index): <WORKDIR>/plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] > plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png (plantuml_demo): <WORKDIR>/plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
[confluence] > objects.inv (index): <WORKDIR>/objects.inv

Being able to confirm you see two or three entries under "finalize assets" might help narrow down the root issue.

[thoerdo]

Hi @jdknight ,

thanks again for the feedback.

I removed all .tox environments, the docs/_build folder and deleted all previously created Confluence pages to make sure the results are clean. Still using the git+https://github.com/sphinx-contrib/confluencebuilder.git@new-am-testing branch as source, butresults are still the same:

• Both PlantUML images are created, yet
• Only the PlantUML image on index.rst is uploaded, while the image on plantuml_demo.rst is not uploaded.

Build logs are as follows:

[new config] 2 added, 0 changed, 0 removed
reading sources... [ 50%] index
reading sources... [100%] plantuml_demo

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... [confluence] setting parent of plantuml_demo to: index
[confluence] mapping index to title: PlantUML Demo_TMP
[confluence] track index toc-depth: 2
[confluence] mapping index/#plantuml-demo to target: PlantUMLDemo
[confluence] mapping /#plantuml demo to target: PlantUMLDemo
[confluence] mapping plantuml_demo to title: Demo_TMP
[confluence] mapping plantuml_demo/#demo to target: Demo
[confluence] mapping /#demo to target: Demo

pre-process assets... [ 50%] index
[confluence] pre-processing doctree (index) for assets...
pre-process assets... [100%] plantuml_demo
[confluence] pre-processing doctree (plantuml_demo) for assets...

done
copying assets...
copying assets: done
[confluence] process image node: <WORKDIR>/docs/_build/confluence/plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] setup attachment key (index): plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] process image node: <WORKDIR>/docs/_build/confluence/plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
[confluence] setup attachment key (plantuml_demo): plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
writing output... [100%] plantuml_demo

publishing documents... [ 50%] index
[confluence] tracking docname index's upload id: 1313250755
publishing documents... [100%] plantuml_demo
[confluence] tracking docname plantuml_demo's upload id: 1313250757

building intersphinx...
[confluence] (intersphinx) index std:doc -1 pages/viewpage.action?pageId=1313250755 PlantUML Demo
[confluence] (intersphinx) plantuml_demo std:doc -1 pages/viewpage.action?pageId=1313250757 Demo
[confluence] registering intersphinx database attachment
[confluence] adding manual attachment: <WORKDIR>/docs/_build/confluence/objects.inv
[confluence] setup attachment key (index): objects.inv
[confluence] finalize assets (total: 2)...
[confluence] > plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png (index): <WORKDIR>/docs/_build/confluence/plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] > objects.inv (index): <WORKDIR>/docs/_build/confluence/objects.inv
publishing assets... [ 50%] plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
publishing assets... [100%] objects.inv

Publish point: ...
building manifest...

====================== slowest reading durations =======================
0.027 index
0.024 plantuml_demo
build succeeded.
  confluence: OK (14.25=setup[9.33]+cmd[4.93] seconds)
  congratulations :) (14.27 seconds)

--> Still only two assets listed in finalize assets section.

And scb-manifest.json still only contains the first image from the index.rst file:

{
    "type": "SphinxConfluenceBuilder/Manifest",
    "spec": 1,
    "language": "en",
    "pages": [
        {
            "id": "index",
            "title": "PlantUML Demo_TMP",
            "isRoot": true,
            "hash": {
                "sha256": "3d9488ca894da19dc2044ea1c17f5d73464f8faa971d1c855bfb9dd8c80787a3"
            },
            "path": "index.conf"
        }
    ],
    "attachments": [
        {
            "id": "plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png",
            "pageId": "index",
            "pageTitle": "PlantUML Demo_TMP",
            "mimeType": "image/png",
            "hash": {
                "sha256": "dc35236e1cb67c7d9483d3bf9f51e1614f9ee24226eeae3d3b3166dd064bbdf4"
            },
            "path": "plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png"
        },
        {
            "id": "objects.inv",
            "pageId": "index",
            "pageTitle": "PlantUML Demo_TMP",
            "mimeType": "application/octet-stream",
            "hash": {
                "sha256": "379afa0a95e80ad89c5c137246271ff483063d9ac4bc75414e4b9ff47246b437"
            },
            "path": "objects.inv"
        }
    ],
    "confluencebuilderVersion": "2.15.0.dev0",
    "sphinxVersion": "8.2.3",
    "docutilsVersion": "0.21.2",
    "generated": "2025-09-16T06:20:35.830676+00:00"
}

--> Still only one images listed in the manifest

[jdknight]

Thanks again for performing more tests and providing information.

Odd to have three attachment keys setup but then only two assets to finalize with:

[confluence] setup attachment key (index): plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] setup attachment key (plantuml_demo): plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
[confluence] setup attachment key (index): objects.inv
...
[confluence] finalize assets (total: 2)...

Examining the implementation and I have still have not figured out how this is possible. I have updated the branch again with more logs... which should give a more explicit indication of assets created/stored. If you are willing to try again, it would be helpful.

Also, mind reporting an extended Python version dump?

python -VV

I am just curious if the interpreter is running in a free-threading mode.

[thoerdo]

Sure things, and thanks for the continuous support.

Updated build log

[new config] 2 added, 0 changed, 0 removed
reading sources... [ 50%] index
reading sources... [100%] plantuml_demo

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents...
[confluence] setting parent of plantuml_demo to: index
[confluence] mapping index to title: PlantUML Demo_TMP
[confluence] track index toc-depth: 2
[confluence] mapping index/#plantuml-demo to target: PlantUMLDemo
[confluence] mapping /#plantuml demo to target: PlantUMLDemo
[confluence] mapping plantuml_demo to title: Demo_TMP
[confluence] mapping plantuml_demo/#demo to target: Demo
[confluence] mapping /#demo to target: Demo
pre-process assets... [ 50%] index
[confluence] pre-processing doctree (index) for assets...
pre-process assets... [100%] plantuml_demo
[confluence] pre-processing doctree (plantuml_demo) for assets...

pre-process assets: done
copying assets...
copying assets: done
[confluence] process image node (index): <WORKDIR>p/docs/_build/confluence/plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] new attachment (dc35236e): <WORKDIR>p/docs/_build/confluence/plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] setup attachment key (index): plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] process image node (plantuml_demo): <WORKDIR>p/docs/_build/confluence/plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
[confluence] new attachment (cb1aaec2): <WORKDIR>p/docs/_build/confluence/plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
[confluence] setup attachment key (plantuml_demo): plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
writing output... [100%] plantuml_demo

publishing documents... [ 50%] index
[confluence] tracking docname index's upload id: 1313256728
publishing documents... [100%] plantuml_demo
[confluence] parent changed: Demo_TMP
[confluence] tracking docname plantuml_demo's upload id: 1313250757

building intersphinx...
[confluence] (intersphinx) index std:doc -1 pages/viewpage.action?pageId=1313256728 PlantUML Demo
[confluence] (intersphinx) plantuml_demo std:doc -1 pages/viewpage.action?pageId=1313250757 Demo
[confluence] registering intersphinx database attachment
[confluence] adding manual attachment: <WORKDIR>p/docs/_build/confluence/objects.inv
[confluence] new attachment (b1ad6fb1): <WORKDIR>p/docs/_build/confluence/objects.inv
[confluence] setup attachment key (index): objects.inv
[confluence] finalize assets (total: 2)...
[confluence] > plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png (index): <WORKDIR>p/docs/_build/confluence/plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] > objects.inv (index): <WORKDIR>p/docs/_build/confluence/objects.inv
publishing assets... [ 50%] plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
publishing assets... [100%] objects.inv

Updated scb-manifest.json

{
    "type": "SphinxConfluenceBuilder/Manifest",
    "spec": 1,
    "language": "en",
    "pages": [
        {
            "id": "index",
            "title": "PlantUML Demo_TMP",
            "isRoot": true,
            "hash": {
                "sha256": "3d9488ca894da19dc2044ea1c17f5d73464f8faa971d1c855bfb9dd8c80787a3"
            },
            "path": "index.conf"
        }
    ],
    "attachments": [
        {
            "id": "plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png",
            "pageId": "index",
            "pageTitle": "PlantUML Demo_TMP",
            "mimeType": "image/png",
            "hash": {
                "sha256": "dc35236e1cb67c7d9483d3bf9f51e1614f9ee24226eeae3d3b3166dd064bbdf4"
            },
            "path": "plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png"
        },
        {
            "id": "objects.inv",
            "pageId": "index",
            "pageTitle": "PlantUML Demo_TMP",
            "mimeType": "application/octet-stream",
            "hash": {
                "sha256": "b1ad6fb1c31024a7e8b933cf1667ce52a7af4db0444d8d41496220cf0ffb62ae"
            },
            "path": "objects.inv"
        }
    ],
    "confluencebuilderVersion": "2.15.0.dev0",
    "sphinxVersion": "8.2.3",
    "docutilsVersion": "0.21.2",
    "generated": "2025-09-17T06:57:05.286289+00:00"
}

-> Still same result.

python -vv result is: Python 3.12.3 (main, Aug 14 2025, 17:47:21) [GCC 13.3.0]

[thoerdo]

Found a solution

My Sphinx build command as stated before is:

sphinx-build -a -b confluence -E -n -j auto -T -v -W --keep-going --color docs docs/_build/confluence {posargs}.

When switching this to:

sphinx-build -a -b confluence -E -n -T -v -W --keep-going --color docs docs/_build/confluence {posargs}.

It works, and all images are properly uploaded:

[confluence] finalize assets (total: 3)...
[confluence] > plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png (index): <WORKDIR>p/docs/_build/confluence/plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
[confluence] > plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png (plantuml_demo): <WORKDIR>p/docs/_build/confluence/plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
[confluence] > objects.inv (index): <WORKDIR>p/docs/_build/confluence/objects.inv
publishing assets... [ 33%] plantuml-fc4101f7f9dbce27bfcc9f0fcf7a3e021073b090.png
publishing assets... [ 67%] plantuml-aafdf2d45a72c216e505c7aa2c461e28295fb64a.png
publishing assets... [100%] objects.inv

I also tried remvoing the -j auto option for the sphinx-build commands in our bigger test environment with a lot more pages and several other Sphinx extension installed, and it worked immediately. All PlantUML images are properly uploaded.

So, the problem seems to be, when sphinx-build runs parallel jobs during the build process.

Initial root cause analysis

1. As the plantuml extension properly creates the image properly, I'd rule out this extension.
2. As sphinx-build with the -j auto options works when creating plain HTML pages, using tox -e html (see tox.ini in initial message) and all images are properly placed in the _images folder and linked / visible on the created HTML pages, I'd also rule out sphinx-build as the root cause.
3. Thus only leaves confluencebuilder extension as properly root cause.

-> Not sure whether this helps.

Happy to do some more testing, if this help finding the root cause.