ai-for-dummies/submitted-skills/Marcos Silva/skills/diagram-plantuml/references/troubleshooting.md

PlantUML Troubleshooting

Symptoms and fixes for the four classes of rendering failure on BASS Confluence.

Macro renders as plain text

Cause	Fix
Macro name wrong (PlantUML, Plantuml)	Use plantuml, lowercase
Body inside <ac:rich-text-body>	Move to <ac:plain-text-body>
Macro opened but not closed	Add the matching </ac:structured-macro>
Page is in wiki renderer mode	Re-save in storage format (page properties → editor)

Diagram renders empty

Cause	Fix
@startuml / @enduml missing	Add both, even if PlantUML accepts bodies without
Body has unescaped < / > outside CDATA	Wrap entire body in <![CDATA[ … ]]>
!include points to a stdlib the plugin doesn't ship	Replace with hand-drawn equivalent
File-size limit exceeded (very large diagrams)	Split into multiple diagrams

Diagram crops on the right

Cause	Fix
Width > ~900 px	Split the diagram horizontally into two, or simplify
Long labels on long arrows	Shorten labels; move detail to body text
Padding parameters set too high	Drop skinparam Padding, skinparam Margin overrides

Theme reverts to dark on dark space

Cause	Fix
Page theme overrides the diagram theme	Use !theme plain explicitly at the top of the body
BASS theme override	Hard-code colors with skinparam per element

C4 / standard library includes fail

Cause	Fix
Plugin doesn't ship the stdlib	Switch to component diagram or hand-drawn boxes
Include URL is blocked by network policy	Mirror the stdlib locally, use !include /path/to/C4_Container.puml (only if the plugin supports it)

Debugging loop

1. Save the .puml body to a file.
2. Run plantuml -tpng -checkonly -failfast2 file.puml.
3. If local parse fails, the body is wrong — fix the syntax.
4. If local parse succeeds but Confluence fails, the wrapper is wrong — fix the storage macro form.

When to give up on PlantUML

• The diagram needs interactivity (hover, click). Confluence PlantUML does not support this.
• The diagram needs real images (logos, photos). Drop them in via attachment instead.
• The diagram needs to be edited by non-technical authors. PlantUML is not the right tool.

When to escalate

• The BASS plugin version changes and breaks a working diagram. Capture the diff, fix the diagram, and update this troubleshooting page.