PlantUML for Confluence not working? Diagnosis and fixes

A PlantUML macro that rendered fine last month is now an error box, and the pages it lived on are the ones people actually read. Before you rebuild anything, it's worth knowing which of four distinct failures you're looking at — because they have very different fixes, and only one of them is really bad news.

First, the reassurance: your diagrams are text

Whatever broke, your diagrams are almost certainly not lost. A PlantUML diagram is its source text, and most Confluence PlantUML apps store that source in the macro body, inside the page. Open the page editor, open the macro, and the text is usually still there — even when the rendered image is not. Everything below is about getting that text rendering again; the text itself survives the app that displayed it.

Failure 1: the app itself is broken or stalled

The clearest real-world example is public: in March 2025, users of a free PlantUML app for Confluence Cloud reported macros failing with an "App update required — version is outdated due to a deprecated platform component" error, with no update available for admins to install. The Atlassian Community thread was never marked resolved; the practical advice it collected was to switch apps.

You can recognize this failure by its shape: every PlantUML macro on every page breaks at once, the error mentions the app or platform version rather than your diagram, and there's nothing in your own configuration to fix. The app's platform dependency moved and the app didn't move with it. Check the app's Marketplace listing for an update; if none exists and none is coming, skip to the switching section below.

Failure 2: the render server is unreachable

PlantUML macros render by requesting an image from a PlantUML server. If that request can't complete, the macro is fine but the picture never arrives. Two common versions:

• The public server is blocked from your network. Corporate proxies and egress filtering sometimes block plantuml.com. Test by opening the public server directly in a browser on the same network.
• Your self-hosted server is down or its certificate expired. If your site uses bring-your-own-server, the renderer is your infrastructure — check the container and the TLS termination in front of it.

Failure 3: CORS misconfiguration (self-hosted setups)

If diagrams stopped rendering right after you deployed or changed a private PlantUML server, open the browser console on an affected page. A CORS error there usually means the response carries duplicate Access-Control-Allow-Origin headers — the bundled Tomcat emits one and a reverse proxy adds another, and browsers reject the pair. The fix and the verification command are in our self-hosted setup guide.

Failure 4: it's the diagram, not the app

If exactly one diagram fails while others render, it's the source. Paste it into any PlantUML server's web form and you'll get a line-numbered syntax error instead of Confluence's less helpful blank. Includes and custom skin parameters that reference files on a server you no longer run are the classic case after a migration.

If you need to switch apps

Switching a PlantUML app is mechanical, because the asset is plain text: install the new app, open each affected page, insert the new macro, paste the source from the old one. Tedious in proportion to your diagram count, but not risky — and scriptable against the Confluence REST API at volume.

The selection criteria are the interesting part, and the March 2025 thread is the argument for making openness one of them. A free app whose code you can't see and whose renderer you can't run is free right up until it stalls — and then your only move is waiting. An open-source app changes that math: the code is public, so what it does with your diagram source is checkable; and if it supports bring-your-own-server, the renderer is infrastructure you own rather than a service you hope stays up.

The honest caveat

No Confluence Cloud app is immune to failure 1 — Forge and Connect platforms evolve, and every app has to keep up, including ours. The realistic goal isn't an app that can never break; it's an app whose failure you can see coming (public code, public changelog) and whose failure costs you nothing you can't recover (source stored in your pages, renderer you can point elsewhere). Judge any PlantUML app — this one included — on those two properties.