# 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.