Eriksen Labs Support

Confluence PDF export failed on pages with many Forge macros. Atlassian has fixed it.

Timings measured on 24 and 25 September 2026 We make a diagrams app for Confluence (disclosure)

Short answer

  • Who it affected: Confluence Cloud pages with many Forge Custom UI macros whose adfExport function returned null for PDF. The export sat at 0% for about four minutes, then failed with “Something went wrong”.
  • Status: fixed. Atlassian tracked it as CONFCLOUD-85221 and states that the fix shipped on 2 November 2026 and reached every site. We have not re-run our tests since then.
  • What to do now: admins need to do nothing. Forge developers can return null for PDF again, and should still test a page with many macros before each release that touches exports.

What we saw

In September 2026 we added Word export to our Mermaid diagrams app. In Forge, that means declaring an adfExport function, which Confluence calls for each macro to get content for the export.

For PDF we wanted to keep the live rendering, so the function returned null. That is the documented path: per the resolution of CONFCLOUD-83083, null for PDF falls back to native PDF rendering.

A page with one diagram exported fine. A page with many did not export at all.

How we measured it

Same app, same site, same content, with only the number of macros changed (25 September 2026):

Macros on the page, adfExport returning null for PDFResult
1PDF ready in 31 s
8PDF ready in 73 s
12Failed after 245 s
18Failed after 242 s

Controls on the same site, the day before:

ControlResult
18 macros, adfExport not declaredReady in under 52 s
30 macros, adfExport not declaredReady in about 60 s
30 macros, adfExport returning real content for PDFReady in about 31 s
30 macros, returning null, emitsReadyEvent set to falseThe same failure
Seconds to a PDF, by number of macros Seconds to a ready PDF by number of macros on the page, on one Confluence Cloud site, 24 and 25 September 2026. With adfExport returning null for PDF: 1 macro, ready in 31 seconds; 8 macros, 73 seconds; 12 macros, failed after 245 seconds; 18 macros, failed after 242 seconds. Controls: 18 macros with adfExport not declared, under 52 seconds; 30 macros with adfExport not declared, about 60 seconds; 30 macros returning real content for PDF, about 31 seconds. adfExport returns null for PDFfailedControls: no adfExport, or real content for PDFFailed with “Something went wrong”06012018024018121830 Seconds to a ready PDF Macros on the page 1 macro, adfExport returning null for PDF: ready in 31 sReady in 31 s8 macros, adfExport returning null for PDF: ready in 73 sReady in 73 s12 macros, adfExport returning null for PDF: failed after 245 sFailed after 245 s18 macros, adfExport returning null for PDF: failed after 242 sFailed after 242 s18 macros, No adfExport — under 52 sNo adfExport: under 52 s30 macros, No adfExport — about 60 sNo adfExport: about 60 s30 macros, Real content for PDF — about 31 sReal content for PDF: about 31 s
The timings in the two tables above, as one chart. Crosses are exports that failed with “Something went wrong” after about four minutes. Our runs on one site, 24 and 25 September 2026.

So the macros themselves were not the problem. Only the null path failed.

What we ruled out

  • A slow or failing function. The Forge logs showed one adfExport invocation per macro, all within about a second, each finishing in under a second without throwing.
  • The invocation-rate limit. CONFCLOUD-82734 describes exports on pages with very many adfExport macros reaching Forge's rate limit. That is a different issue: here every invocation ran and returned.
  • The ready event. With emitsReadyEvent set to false, the page failed the same way.

What was left was on Confluence's side, after our function had answered.

An independent reproduction

We posted the numbers in the Atlassian Developer Community and raised a ticket with Atlassian on 28 September. The same day, another developer reproduced it on a separate Forge app and a separate site, with a heavier macro (a bundle of about 3.5 MB, against roughly 635 kB for our Mermaid core chunk):

Their testResult
1 macro, null for PDF35 s
8 macros, null for PDF38 s
12 macros, null for PDFFailed at 241 s, twice
18 macros, null for PDFFailed at 254 s
18 macros, real content for PDF36 s
18 macros, no adfExport23 s

The same pattern on a second app and site made the report much stronger than our numbers alone.

Atlassian Developer Support then reproduced it and filed CONFCLOUD-85221 on 5 October. Our later controlled runs showed the failure was intermittent, not a fixed threshold at 12 macros, and Atlassian updated the description to match.

Our workaround

When a diagram is saved, the editor stores a PNG of it in the macro's configuration. For PDF, adfExport returns that picture, and only a diagram with no usable picture still gets null. In outline:

export async function adfExport(payload) {
  const pdf = payload?.exportType === 'pdf';
  try {
    const image = storedImage(payload); // saved with the macro, checked before use
    if (image) return imageDoc(image);  // PDF and Word get the picture
    if (pdf) return null;               // no picture: fall back to the live render
    return codeBlockDoc(payload);       // Word must never get null
  } catch {
    return pdf ? null : placeholderDoc();
  }
}

Two details matter. The handler never throws, because a throw makes the PDF exporter silently drop the macro (CONFCLOUD-85030). And the stored picture is checked before use: a complete PNG, within a size budget, and still matching the diagram's current source and theme.

With stored pictures, our 30-macro page exported in 31 seconds. The cost is that a PDF carries a raster picture instead of a vector diagram.

Atlassian's stated cause and fix

CONFCLOUD-85221 was closed as Fixed on 2 November 2026. Atlassian Developer Support told us the fix covers this case, shipped that day and reached every site. The cause, in their words: “Iframe style injection could stall indefinitely and block PDF generation.” The change bounds the total wait, limits browser work on pages with many iframes and adds monitoring.

There is no release note, because it was an internal backend change with nothing different in the Forge UI or the API contracts.

What Forge developers should do now

  • Returning null for PDF is a supported path again, according to Atlassian. If you removed adfExport or delayed Word export because of this bug, you can revisit that.
  • A stored picture is still worth keeping if you have one. It was the fastest path in our measurements, and it does not depend on every iframe rendering during the export. We are keeping it in Mermaid & PlantUML Diagrams for Confluence, with null as the fallback for diagrams that have no picture.
  • Test pages with many macros, not one. Build test pages with 1, 8, 12, 18 and 30 macros. Time each export from the click until the file is ready.
  • Run each size more than once. This failure was intermittent.
  • Keep two controls: the same page with adfExport not declared, and with it returning real content for PDF. If only the null path is slow, you know where to look.
  • Read the Forge logs: one invocation per macro, how long each took, and whether any threw.

How we work

We test exports on pages the size our customers really have, and we keep the numbers. When something breaks outside our own code, we report it upstream with a reproduction and ship what we can in the meantime. Thanks to Atlassian Developer Support for reproducing this, fixing it and explaining the cause.

Questions

Why does Confluence PDF export fail with many Forge macros?

Until 2 November 2026, Confluence Cloud could fail to export a page to PDF when it held many Forge Custom UI macros whose adfExport returned null for PDF. Atlassian tracked it as CONFCLOUD-85221 and states it is fixed on every site. If exports still fail, a different cause is likely, such as the invocation-rate limit on pages with very many macros (CONFCLOUD-82734).

Should adfExport return null for PDF?

It can. Returning null for PDF tells Confluence to use its native PDF rendering of the live macro, per CONFCLOUD-83083, and Atlassian states the failure on pages with many macros is fixed. If your macro can store a picture of its content, returning that picture avoids the live render during export. Never return null for Word.

Do Confluence admins need to do anything about CONFCLOUD-85221?

No. Atlassian states the fix shipped on 2 November 2026 as a backend change and reached every site. There is nothing to install or update. If a PDF export of a page with many macros still fails, contact the app vendor or Atlassian support with the page's macro count.

How do I test PDF export for a Forge macro?

Export pages with 1, 8, 12, 18 and 30 macros, more than once each, and time them. Compare against the same pages with adfExport not declared and with it returning real content. Check the Forge logs for one invocation per macro, its duration and any errors.

Sources and changes

Timings are our own, on one Confluence Cloud site, and the independent reproduction’s as posted in the community thread. Atlassian’s cause and the date of the fix are as Atlassian Developer Support stated them to us in November 2026. We have not re-run the tests since the fix.

Changelog

  • . First version.

Corrections

None yet. If something here is wrong, email [email protected].