Mermaid Troubleshooting: Fix Common Syntax Errors and Rendering Problems

# Mermaid Troubleshooting: Fix Common Syntax Errors and Rendering Problems

Every Mermaid user eventually pastes a diagram and gets an error like Parse error on line 6 or Syntax error in text. The diagram renders as a block of raw text, or it renders blank. This is normal — Mermaid is a grammar-based tool, and the same handful of mistakes cause most failures.

This guide covers the most common Mermaid syntax errors, why they happen, and how to fix them. It works for Mermaid live editors like MermaidEditor.lol, GitHub READMEs, Notion, VS Code, Obsidian, and any other Mermaid renderer.

The Error Box and How to Read It

When Mermaid cannot render a diagram, most tools show an error panel instead of the picture. The message usually includes a line number:

Parse error on line 6:
...
Expecting '...', got '...'

The line number is the biggest hint. Go to that line in your source and look for the mistakes described below. In MermaidEditor.lol, errors are shown live as you type, which makes debugging much faster.

1. Missing or Extra Closing Brackets

Mermaid flows are built from nodes and edges. Forgetting a bracket, or adding one too many, breaks the whole flow.

Common mistake:

flowchart LR
  A[Start] --> B{Check
  B --> C[Done]

Here B{Check is missing its closing }. The fix:

flowchart LR
  A[Start] --> B{Check}
  B --> C[Done]

Count every {, [, and ( against its closing pair. An unbalanced bracket is the single most common Mermaid error.

2. Special Characters Inside Labels

Square brackets, braces, and parentheses have meaning in Mermaid syntax. If you put them directly in a label, the parser reads them as structure, not text.

Problem:

flowchart LR
  A[User clicks (Submit)] --> B[Save]

The parentheses inside [User clicks (Submit)] confuse the parser. Fix it by quoting the label or using round node shapes:

flowchart LR
  A["User clicks (Submit)"] --> B[Save]

3. Using HTML-Style Entity Characters

If you copy text from a web page or a chat tool, you sometimes import &, <, or > instead of plain characters. These can produce odd errors.

Problem:

flowchart LR
  A[Tom & Jerry] --> B[Cartoon]

Fix by using the literal character and quoting:

flowchart LR
  A["Tom & Jerry"] --> B[Cartoon]

When in doubt, wrap labels that contain &, <, >, or special punctuation in double quotes.

4. Whitespace and Line Indentation

Different Mermaid diagram types are picky about indentation. Flowcharts are lenient, but diagrams like sequenceDiagram, stateDiagram, and mindmap may fail if you indent or de-indent inconsistently.

For example, in a mindmap, the nesting level defines the tree structure:

mindmap
  root((Project))
    Planning
      Research
    Build
      Code

If you mix spaces and tabs, or break the indentation level, the diagram can fail or render wrong. Keep consistent indentation and avoid tabs.

5. Wrong Diagram Type Keywords

Each Mermaid diagram type uses its own keyword on the first line. Using an old or wrong keyword fails.

Common outdated or misspelled keywords:

- graph and graph TB are valid for flowcharts, but the modern keyword is flowchart.

- sequence alone is wrong — it must be sequenceDiagram.

- class alone is wrong — it must be classDiagram.

- er is wrong — it must be erDiagram.

The keyword must be the very first thing in the code block, with nothing before it except the opening fence.

6. Sequence Diagram Participant Errors

Sequence diagrams fail when aliases and messages don't match. If you initialize a participant, then reference a different name, the message targets the wrong actor or errors out.

Problem:

sequenceDiagram
  participant A as Client
  participant B as Server
  A->>Server: Hello
  Server-->>A: World

The aliases are A and B, but the messages use Server and Client. Fix by using the aliases, or use straightforward names:

sequenceDiagram
  participant Client
  participant Server
  Client->>Server: Hello
  Server-->>Client: World

7. State and Class Diagram Arrow Issues

In class diagrams, the arrow syntax is sensitive. Using the wrong combination of dashes, brackets, and letters produces parse errors.

Valid relationships:

classDiagram
  Animal <|-- Dog
  Animal : +int age
  Dog : +bark()
  Dog --> Bone : uses

If a relationship line has a typo like Dog --|> Bone in the wrong direction, or unbalanced ( ) on a method definition, the diagram fails. Keep method signatures balanced.

8. Blank Diagram Renders

Sometimes Mermaid shows no error but renders a blank box. This usually happens when:

- There is nothing but comments or whitespace after the diagram keyword.

- The diagram is rendered without the keyword, so Mermaid does not know what to draw.

- An SVG CSS rule hides it (less common in editors, more in custom embeds).

Check that your code block actually starts with a valid Mermaid keyword and contains at least one node, shape, or message.

9. Team Projects: Copying From a Messy Source

Errors often come from copying diagrams that were already broken, or that use features your renderer does not support. Before debugging, paste the diagram into MermaidEditor.lol and watch it render live. Then:

1. Remove the code block fence and any surrounding markdown.
2. Confirm the first line is the diagram keyword.
3. Rebuild the diagram by adding one node at a time.

Building incrementally isolates the problem line quickly.

10. Theme and Dark Mode Render Oddities

If a diagram renders but looks wrong — invisible text, broken colors — the issue is usually theme-related, not syntax. Mermaid themes like dark and neutral can clash with a page's background.

%%{init: {"theme": "dark"}}%%
flowchart LR
  A[Rendered] --> B[Check]

If text is hard to read in a dark theme, try the base or neutral theme, or set themeVariables explicitly to control colors.

A Quick Debugging Checklist

When a Mermaid diagram will not render:

1. Does the first line contain a valid, spelled-correctly diagram keyword?
2. Are all brackets, braces, and parentheses balanced?
3. Are labels with special characters quoted?
4. Is the line number in the error message pointing at the real culprit?
5. Did you accidentally use HTML entities or copy-paste markup?
6. Does the diagram render when built one node at a time in an editor?

Final Thoughts

Most Mermaid errors come from a short list of causes: unbalanced brackets, special characters in labels, wrong keywords, and broken indentation. Learn to read the error's line number, rebuild the diagram incrementally, and test in a live editor before committing it to a README or documentation site.

If you hit an error you cannot crack, paste the exact source and the full error message into MermaidEditor.lol — the live error highlighting usually points straight to the fix.