Practical diagram guide

Fix Mermaid parse errors, overflowing text and blank exports

Updated 11 September 2026

A practical troubleshooting guide for Mermaid syntax errors, long labels, export formatting, and browser storage.

Start with the reported line

If a diagram stops rendering after an edit, undo the last change and add it back in smaller steps. Check the reported line and the line immediately before it. A missing closing quote or bracket can make the next line look like the source of the error.

The editor keeps the last successful preview when possible. Treat the stale-preview notice as a signal that the visible diagram does not yet match the source.

Text extends beyond a box

Use the Node Defaults font-size control instead of applying a font-size change after rendering. Boxes must be measured with the same text size that will be displayed. For long headings, use a deliberate line break such as <br/> inside a quoted label, or a Mermaid Markdown string that can wrap.

Increase spacing if neighboring nodes overlap. Increasing export padding adds space around the whole diagram; it does not enlarge individual node boxes.

Formatting disappears in another application

Export with the updated SVG path, which uses native SVG text instead of embedded HTML labels. If a receiving application substitutes a font, the appearance may still change. Use PNG when you need the recipient to see a fixed raster image. Keep the MMD source alongside the image so you can edit it later.

The editor will not load

The application serves Mermaid and supporting libraries from the same site. Check your connection and whether your network or a browser extension blocks a required script. The editor does not promise an offline first load. Review the browser network error before retrying.

Look the exact message up

Every parser message this build produces has its own page with the cause, the source that fails, and source that renders. Start from the Mermaid error dictionary, or paste the whole block into the repair tool, which applies fifteen corrections at once and shows every change.

Protect work saved in your browser

Local projects belong to this browser profile and site origin. Clearing browser data, moving to another domain, or using a different device does not carry those projects over. Download a JSON project backup from Export before clearing storage. Copying a share link makes its diagram accessible to anyone who receives that link.

Try it in the editor

Edit this formatted delivery flow in Mermaid, inspect the rendered result, and adapt the working source for your own documentation.

flowchart LR
  A["<b>Plan</b><br/>Define the scope"] --> B["<b>Build</b><br/>Implement and test"]
  B --> C["<b>Ship</b><br/>Review the result"]