How to Fix Common Mermaid Syntax Errors

"Syntax error in text" and "Parse error on line X" are the messages every Mermaid user sees eventually. The good news: almost all errors come from a handful of mistakes. The MermaidViewer editor highlights the failing line, and the AI Fix button can repair broken code automatically — but it's worth knowing the usual suspects.

1. Special characters in labels

Parentheses, brackets, quotes, colons and semicolons have meaning in Mermaid. Wrap labels that contain them in double quotes.

%% Broken
flowchart LR
    A[Call api(v2)] --> B

%% Fixed
flowchart LR
    A["Call api(v2)"] --> B

2. Lowercase end as a node

end closes subgraphs and blocks. A node called end breaks the diagram. Use End, finish or ["end"].

3. Missing or misspelled diagram keyword

The first line must be a valid keyword: flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt, pie, mindmap and so on. Keywords are case-sensitive: sequencediagram fails.

4. Wrong arrow syntax for the diagram type

Each diagram has its own arrows. --> works in flowcharts, but sequence diagrams need ->> or -->>, and ER diagrams need cardinality markers like ||--o{.

5. Unclosed blocks

Every subgraph, loop, alt, opt, par, rect and composite state needs a matching end. Indent nested blocks so missing ends are easy to spot.

6. Indentation in mindmaps and kanban

Mindmaps, treemaps and kanban boards use indentation for hierarchy. Mixing tabs and spaces or inconsistent indents creates wrong trees or errors. Use two spaces consistently.

7. Spaces in ids

Node ids cannot contain spaces. Use userService[User service], not User service --> DB.

8. Colons in sequence messages and Gantt tasks

In sequence diagrams the first colon separates the arrow from the message text; in Gantt charts the colon separates the task name from its metadata. Avoid extra colons in names or escape them with #58;.

9. Invalid dates in Gantt charts

Dates must match dateFormat. If you declare dateFormat YYYY-MM-DD, a date like 01/02/2026 fails.

10. Unsupported diagram type for the renderer

Newer types (architecture, radar, treemap, kanban) need a recent Mermaid version. They work in MermaidViewer, but older platforms may show an error. Export an image for those platforms.

11. Smart quotes and invisible characters

Copying from Word or Slack can insert curly quotes (“ ”) or non-breaking spaces. Replace them with straight quotes and normal spaces.

12. Comments in the wrong place

Comments must start with %% on their own line. Inline comments after code can break parsing in some diagram types.

Let AI fix it

Paste the broken diagram into the editor and click AI → Fix syntax. The AI reads the error message and your code, repairs the syntax and keeps your structure. You can review the fix before accepting it.