Bug Report: sphinxcontrib.confluencebuilder - 415 Unsupported Media Type when uploading objects.inv and png files into Confluence Cloud

[PhorstenkampFuzzy]

Project: sphinx-contrib/confluencebuilder
Version: 3.0.0 (from build log)
Environment:

• OS: Linux (6.8.0-101-generic-x86_64)
• Python: 3.13.0 (CPython)
• Sphinx: 9.1.0
• Docutils: 0.22.4
• Jinja2: 3.1.6
• Pygments: 2.19.2
• Confluence Instance: Confluence Cloud (api.atlassian.com endpoint detected)

Description:
The sphinxcontrib.confluencebuilder (v3.0.0) fails with a 415 Unsupported Media Type error when attempting to publish generated documentation to a Confluence Cloud instance. The error specifically occurs during the "publishing assets" phase, targeting the objects.inv file, which is an intersphinx inventory.

Observed Behavior:
The build process attempts to upload objects.inv using a POST request to a legacy Confluence Server API endpoint (/rest/api/content/***/child/attachment/***/data) while other operations (e.g., fetching pages) appear to use the modern Confluence Cloud v2 API. The request sends data with Content-Type: multipart/form-data, but the Confluence API responds with HTTP 415, indicating the media type is not supported for that endpoint, and the builder's traceback reports DATA: <not-or-invalid-json>. This suggests a mismatch in the expected data format for attachment uploads on Confluence Cloud when using this specific endpoint.

Steps to Reproduce:

1. Set up a Sphinx project configured to use sphinxcontrib.confluencebuilder.
2. Configure conf.py to publish to a Confluence Cloud instance.
   • Ensure confluence_publish_intersphinx is either True (default) or not explicitly set.
3. Execute the build command: make confluence (or equivalent sphinx-build -b confluence ...).

Expected Behavior:
The objects.inv file should be uploaded successfully to Confluence Cloud, or the builder should handle its publication gracefully without terminating the build process. Ideally, for Confluence Cloud targets, all API interactions, including attachment uploads, should consistently use the appropriate Confluence Cloud v2 API endpoints and their expected data structures.

Technical Details from Log:

#22 10.50 publishing assets... [100%] objects.inv
#22 10.50 (debug) Request: get_attachment]
#22 10.50 GET https://api.atlassian.com/ex/confluence/***/wiki/api/v2/pages/***/attachments?filename=objects.inv
#22 ... (Successful GET request for attachment metadata via v2 API)
#22 10.50 (debug) Request: store_attachment]
#22 10.50 POST https://api.atlassian.com/ex/confluence/***/wiki/rest/api/content/***/child/attachment/***/data
#22 10.50 User-Agent: SphinxConfluenceBuilder/3.0.0
#22 10.50 Accept-Encoding: gzip, deflate
#22 10.50 Accept: application/json; charset=utf-8
#22 10.50 Connection: keep-alive
#22 10.50 X-Atlassian-Token: no-check
#22 10.50 Content-Length: 2259
#22 10.50 Content-Type: multipart/form-data; boundary=********************************
#22 10.50 Authorization: (redacted)
#22 10.50 (debug) Request data]
#22 10.50 (non-json)
#22 10.56 DEBUG:urllib3.connectionpool:https://api.atlassian.com:443 "POST .../wiki/rest/api/content/***/att***/data HTTP/1.1" 415 0
#22 10.56 (debug) Response]
#22 10.56 Code: 415
#22 ... (truncated response headers)
#22 10.58 sphinxcontrib.confluencebuilder error!
#22 ...
#22 10.59     sphinxcontrib.confluencebuilder.exceptions.ConfluenceBadApiError:
#22 10.59     ---
#22 10.59     Unsupported Confluence API call
#22 ...
#22 10.59     REQ: POST
#22 10.59     RSP: 415
#22 10.59     URL: https://api.atlassian.com/ex/confluence/***/wiki/rest/api/content/***/child/attachment/***/data
#22 10.59     API: rest/api/content/***/child/attachment/***/data
#22 10.59     DATA: <not-or-invalid-json>

Workaround:
Disable the publication of the intersphinx inventory file by adding the following to conf.py:

confluence_publish_intersphinx = False

Note: Setting confluence_publish_intersphinx = False has successfully resolved the immediate build failure for now.

[PhorstenkampFuzzy]

The same issue accoured in another build with an PNG (mermaid build PNG)

Bug Description

When running a build with the confluence builder, the process fails during the asset publishing phase. The error is an HTTP 415 Unsupported Media Type, which occurs when the builder attempts to upload a PNG asset (in this case, generated by sphinxcontrib-mermaid) to a Confluence Cloud instance.

The traceback indicates that the POST request to update an attachment is being sent with a Content-Type of multipart/form-data, but the API responds with a 415 error, suggesting this media type is not supported for the action. This might be due to a recent change in the Confluence Cloud API.

Steps to Reproduce

1. Set up a Sphinx project that uses sphinxcontrib-confluencebuilder to publish to a Confluence Cloud space.
2. Include the sphinxcontrib.mermaid extension and add a Mermaid diagram to a source file.
3. Execute the build using the confluence target (e.g., poetry run make confluence).
4. The build proceeds normally until it reaches the "publishing assets" stage.
5. The build fails when attempting to upload the generated PNG for the Mermaid diagram.

Expected Behavior

The build should complete successfully, with all assets, including the generated Mermaid images, being uploaded to the correct Confluence page.

Actual Behavior

The build terminates with an error. The console output shows a ConfluenceBadApiError and an HTTP 415 status code.

Error Log / Traceback

Here is the relevant portion of the anonymised error log:

(debug) Request: get_attachment]
GET https://[our-confluence-instance].atlassian.net/ex/confluence/[id]/wiki/api/v2/pages/[page-id]/attachments?filename=mermaid-003b4eb851f2ff70be318385d331f0dd8c8b3e21.png
...
(debug) Response data]
{
  "results": [
    {
      ...
      "id": "att[attachment-id]",
      ...
    }
  ],
  ...
}

(debug) Request: store_attachment]
POST https://[our-confluence-instance].atlassian.net/ex/confluence/[id]/wiki/rest/api/content/[page-id]/child/attachment/att[attachment-id]/data
User-Agent: SphinxConfluenceBuilder/3.0.0
...
Content-Type: multipart/form-data; boundary=[boundary-id]
...
(debug) Response]
Code: 415
...

sphinxcontrib.confluencebuilder error!

An unsupported Confluence API call has been made. See the following details for more information:

REQ: POST
RSP: 415
URL: https://[our-confluence-instance].atlassian.net/ex/confluence/[id]/wiki/
API: rest/api/content/[page-id]/child/attachment/att[attachment-id]/data
DATA: <not-or-invalid-json>

Environment

• OS: Linux
• Python version: 3.13.0
• Sphinx version: 9.1.0
• sphinxcontrib-confluencebuilder version: 3.0.0
• Other relevant extensions: sphinxcontrib.mermaid (9.1.0)

[jdknight]

This is unexpected at this time.

It is unclear to me if this is an API change that is being rolled out slowly or if there is an issue with specific spaces due to Marketplace addons. When testing the existing extension on three spaces (personal endpoint and two independent spaces), I only see this issue on one of the spaces (415 for new attachments and 500 errors for attempting to update attachments). What bugs me is why it is only happening on a single space.

I did not observe the issue in the past, but when investigating #1177, the installation of the "KARMA Page Builder for Confluence (Content Formatting)" addon started to cause problems. Not sure if it addon itself was causing issues or issuing an addon update triggered something else to migrate on the backend. Tried to uninstall the addon and no changes, but notice the administration section noting it was flagged for removal in 30 days. Tried to force remove, but still observed the issue. Not sure if its still there hidden in the background waiting for a backend cleanup or if its actually removed. I guess @PhorstenkampFuzzy, if you know you do not have that addon, that might rule this out.

Back to a possible API issue/migration issue, I have not seen any changes in any documentations or the Confluence forums. If anyone sees something otherwise, please let me know. I'll try to do some more investigation in the upcoming days and maybe make a ticket with Atlassian if a solution is still not found.

[jdknight]

Still experiencing odd scenarios where this is triggered. The other day, noticed all three spaces would allow pushing. And then later that evening, one of the spaces had problems again. Testing just now, all attachments could be created/updated on all spaces.

[PhorstenkampFuzzy]

Thank you for being on the ball for this.

[PhorstenkampFuzzy]

Hi,

i talked to our main Confluence Admin. We did not install any new plugins in confluence when the breakdown of the confluence push happend.

[jdknight]

May I see the complete list of headers from a failed attachment POST and its response? For example (knowing that you will have a 415 error over a 200 seen below):

(debug) Request: store_attachment]
POST https://api.atlassian.com/ex/confluence/[GUID]/rest/api/content/[PAGE_ID]/child/attachment/att[AID]/data
User-Agent: SphinxConfluenceBuilder/3.0.0
Accept-Encoding: gzip, deflate
Accept: application/json; charset=utf-8
Connection: keep-alive
X-Atlassian-Token: no-check
Content-Length: 675
Content-Type: multipart/form-data; boundary=(redacted)
Authorization: (redacted)

(debug) Request data]
(non-json)

(debug) Response]
Code: 200
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Date: Fri, 13 Mar 2026 02:10:09 GMT
Server: AtlassianEdge
Vary: Accept-Encoding
X-Confluence-Request-Time: 1773367808739
Cache-Control: no-cache, no-store, must-revalidate
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Encoding: gzip
Atl-Confluence-Via: (redacted)
X-Trace-Id: (redacted)
X-Frame-Options: SameOrigin
X-Content-Type-Options: nosniff
X-Xss-Protection: 1; mode=block
Atl-Traceid: (redacted)
Atl-Request-Id: (redacted)
Strict-Transport-Security: max-age=63072000; preload
Report-To: (redacted)
Nel: {"failure_fraction": 0.01, "include_subdomains": true, "max_age": 600, "report_to": "endpoint-1"}
X-Cache: Miss from cloudfront
Via: (redacted)
X-Amz-Cf-Pop: (redacted)
X-Amz-Cf-Id: (redacted)
Server-Timing: (redacted)

Also curious if you have re-tried the same publish event recently. Asking due to changes made based on CONFCLOUD-83933, although probably unrelated.