11. Troubleshooting and FAQ
| Symptom | Cause | Fix |
|---|---|---|
| A connector cuts straight through a shape | Smart Route is off, or the connector is elbow / straight / curved, or it has hand-placed waypoints | Turn on Smart Route (R); set the connector's routing to orthogonal; right-click → Clear waypoints |
| Several connectors arrive at one box stacked on the same point | Their ports were pinned by hand — pinned ports are never redistributed | Re-drag the ends onto the shape's body rather than onto a specific port |
| The export looks different from the screen | The export dialog's Route connectors around shapes was turned off, or Include header / Include footer differ | Re-open Ctrl/⌘ ⇧ E and check the toggles; the preview is live |
| The exported PNG is blurry when printed | PNG scale is 3× by default | Raise the scale, or export SVG, or export PDF at dpi: 300 |
| Text in the PDF cannot be selected | The PDF artwork is a raster by design | Export SVG if you need live text |
| A label overflows its shape | Text fitting is off for that shape — typing a font size by hand sets it | Inspector ▸ Text fitting ▸ shrink, or resize the shape, or AI labels: shorten to fit |
A label ignores **bold** | It is an ERD attribute line, a table cell or a UML class compartment — content-driven stencils draw their own text | Use markup in the entity/class name, not in the rows |
| A shape will not move | It or its layer is locked | Ctrl/⌘ L, or the padlock on the layer row |
| A shape has vanished | It is hidden, or its layer is | Palette → Show all layers and objects |
| Keyboard shortcuts do nothing | Focus is in a text field, the inline editor, or a dialog — modifier-free keys are deliberately ignored there | Click the canvas first, or press Escape |
Ctrl/⌘ V did nothing | The cursor was in a text field or the inline label editor — the diagram paste handler deliberately ignores editable targets | Click empty canvas first, then paste |
| An import "worked" but shapes are plain rectangles | The source used shapes outside the mapped vocabulary | Check the warnings in the import dialog; morph the rectangles (right-click → Change shape) |
| A whole SVG arrived as one picture | Only SVGs exported by this app re-read as a document | Ask the sender for the original format, or trace it elsewhere |
| Saved diagrams disappeared | They live in localStorage; clearing site data or a different browser profile loses them | Use Export ▸ Plota JSON for anything that matters |
| “Ollama is running but the editor cannot reach it” | OLLAMA_ORIGINS does not include this page's origin — a browser-only restriction, which is why curl works | See the CORS fix |
| The AI panel says it is using lexical search | The embedding model could not be fetched, or you are in the single-file build | Nothing to fix — search, suggestions and lint still work, just less semantically |
| “Load local LLM” is disabled | No WebGPU in this browser | Use Ollama or an OpenAI-compatible server instead |
| A big diagram feels sluggish while dragging | Routing is the expensive part of a re-render on large pages | Turn Smart Route off while you rearrange, or set the busiest connectors to elbow |
| “Mermaid "gantt" diagrams are not supported yet” | That type is a chart, not boxes and arrows, and is refused by name | See the supported types; draw it in Mermaid itself |
| A pasted Mermaid chart is unreadably long, and no split is offered | The offer appears only for a flowchart with two or more subgraphs past 80 shapes or 100 connectors | Group the steps into subgraphs, or run Split into overview + details from the palette |
| The exported file has a small “Made with Plota” mark | The watermark is on by default for SVG, PNG and PDF | Untick Plota watermark in the export dialog (CLI: --no-watermark; MCP: plotaWatermark: false) |
plota render … -f png fails | PNG output needs the sharp image library on that machine | Install it, or render svg |
plota critique exits 1 in CI | A gate failed: the score is above --max-score, or a --fail-on problem is present | Read the per-file report; --json gives the details |
The MCP server answers 401 | The token is missing, mistyped, rotated or revoked | Check the Authorization: Bearer header (or ?token= in a connector URL); get a fresh token from the portal |
| The agent gets a picture but no viewer appears | The host does not support MCP Apps | Ask the agent to export_diagram; over the hosted server the reply carries a download link valid for 30 minutes |
| The viewer says the Plota JSON is too large | The document is over 4 MB | Ask the agent to export_diagram with format: "json" |
An agent never uses run_script | It is offered only when the server runs locally; the hosted server does not list it | Nothing to fix — agents use apply_batch instead |
Getting more detail#
- The status bar's history item names the most recent edit; its tooltip gives the depth of the undo stack.
- The copilot's provider card reports what is degraded in the current
environment; over MCP, the
runtime_infotool does the same. - Import and export failures always name the format that was recognised and what went wrong inside it — read the toast, and the warning block in the import dialog.
- If something is genuinely missing rather than broken, check Known limitations first.
Iconify search does nothing#
The Icons panel searches the bundled catalogue first and falls back to the public Iconify API when nothing matches. When that fallback fails, the panel names the cause. The common one:
The browser blocked the request because this page was opened from a file:// URL. Serve the .html over http (or set a mirror below) and Iconify search works.
A page opened by double-clicking the .html file runs on a file:// origin,
where browsers refuse cross-origin requests. Serving the same file over http
fixes it — any static server will do:
python3 -m http.server 8080 # then open http://localhost:8080/diagrammer.html
The other causes are named too: an HTTP status (a proxy refusing the request) and a timeout. In a network that blocks the public API, put a reachable Iconify mirror in the field the panel shows and press Retry; the bundled sets keep working either way.
Ctrl+Z in the code pane#
The code pane keeps its own undo history, separate from the diagram's. Ctrl/⌘ Z there undoes your typing a run at a time and stops at line breaks. A rewrite
from outside the editor — From canvas, a template, a generated program —
starts a fresh history, so undo cannot walk back into a program that has been
superseded.
"Tidy Up says 0 moved"#
That is a result, not a failure. Tidy Up scores your arrangement against every layout it can produce, including an in-place tidy, and applies one only if it beats what you already have. When nothing does, the bar says "Already tidy — nothing beat your arrangement" and spends no undo step. To force a change, choose a specific algorithm in the Layout panel instead of Automatic.
Saving into a folder#
The Workspace panel offers a real folder even when the .html file is opened by
double-clicking it — Chromium treats a local file as a secure context, and its
directory picker works there. Choose a folder once and every save writes a
.json into it. Save to file… does the same for a single path, and
Save all N pages to a folder… writes one file per page.
Firefox and Safari have no directory picker at all; there the panel says so and Download .json is the route to disk.
Frequently asked#
Is my diagram uploaded anywhere? Not by the editor: it runs in your browser and saves to that browser's storage or to files you export. The network is used only for things you ask for — an icon search that falls back to the public Iconify API, a model download, a model provider you configure — and a diagram you build through the MCP server is, of course, made on that server.
Can I edit a diagram an agent made? Yes. Download Plota JSON from the
viewer (or ask for export_diagram with format: "json") and open it in the
editor with Import Diagram — every page comes across.
Which Mermaid types work? Thirteen; see
Mermaid diagrams. Charts such as gantt and pie are refused
by name.
What does the readability score mean? Lower is better. It counts what makes
a drawing harder to read — crossings, connectors through or along shapes,
overlaps, wasted space — and Explain this layout says which of those cost
the most. The editor, the CLI's critique and the MCP server's
review_diagram report the same score.
Can I turn the watermark off? Yes — the export dialog's Plota watermark
box, --no-watermark on the CLI, or plotaWatermark: false over MCP.
Is the CLI on npm? It will be available on npm soon; see Getting it.