Fix Mermaid rendering issues: syntax errors and debugging

A Mermaid diagram that doesn't render is almost never a Mermaid bug—it's a syntax typo, a mismatched quote, or a keyword spelled wrong. Most errors are obvious once you know what to look for. Here are the ten most common rendering failures and how to fix them.

1. Missing or mismatched quotes in labels

Problem: A label with special characters breaks the diagram.

flowchart TD
    A[User's profile]
    B["User's profile"] ✓

The unquoted User's profile fails because the apostrophe confuses the parser. The quoted version works.

Fix: Wrap any label with quotes, colons, or special characters in double quotes:

A["User's profile"]
B["Cost: $50"]
C["Success (95%)"]

2. Unescaped special characters in code

Problem: Using HTML or Markdown in a label without escaping.

flowchart TD
    A["Step 1: Do <this>"]  ✗
    B["Step 1: Do &lt;this&gt;"]  ✓

Fix: HTML-encode special characters:

• < → <
• > → >
• & → &
• " → "

Or use the MermaidCreator playground — it handles escaping for you when you edit visually.

3. Missing diagram type declaration

Problem: Forgetting the opening keyword.

A --> B --> C  ✗
flowchart LR  ✓
A --> B --> C

Fix: Always start with the diagram type: flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, etc.

4. Typos in arrow syntax

Problem: An arrow is misspelled, so the parser sees two separate statements.

flowchart TD
    A -> B  ✗ (single dash, or arrows are context-specific)
    A --> B  ✓

Fix: Use the correct arrow for your diagram type:

• Flowchart: -->, --->, <--, <-->, -.->
• Sequence: ->>, -->>, -x, --)
• State: --> (same)

5. Mismatched parentheses or braces

Problem: Opening a block (subgraph, alt, loop) but forgetting to close it.

flowchart TD
    subgraph SG["My group"]
        A --> B
        B --> C
    (missing 'end')

Fix: Every subgraph, alt, else, loop, opt, par, and rect must end with end:

flowchart TD
    subgraph SG["My group"]
        A --> B
        B --> C
    end

6. Invalid direction keywords

Problem: Using the wrong letter combo for flowchart direction.

flowchart TOP  ✗
flowchart TD  ✓ (top-down)
flowchart LR  ✓ (left-right)
flowchart BT  ✓ (bottom-top)
flowchart RL  ✓ (right-left)

Fix: Flowchart direction must be exactly TD, LR, BT, or RL.

7. Missing colon in sequenceDiagram participants

Problem: Declaring a participant without the syntax.

sequenceDiagram
    participant A, B, C  ✗
    participant A  ✓
    participant B
    participant C

Fix: Each participant must be on its own line. Use aliases to keep the syntax clean:

sequenceDiagram
    participant C as Client
    participant API
    participant DB as Database

8. Forgotten nodeID in class or ER diagrams

Problem: Referencing a class or entity that was never defined.

classDiagram
    A --> B  ✗ (no class definition)
    class A  ✓
    class B
    A --> B

Fix: Define each class or entity before using it in relationships:

classDiagram
    class User {
        +id: int
    }
    class Post {
        +id: int
    }
    User --> Post

9. Invalid state diagram syntax

Problem: Forgetting [*] for the start/end state, or using state keyword in the wrong way.

stateDiagram
    A --> B  ✗ (no start marked)
    [*] --> A  ✓
    A --> [*]

Fix: Mark the start state as [*] --> and the end as --> [*]. For stateDiagram-v2 (recommended), use the same syntax:

stateDiagram-v2
    [*] --> Idle
    Idle --> Running: start()
    Running --> [*]

10. Whitespace or indentation breaks

Problem: Extra spaces or tabs inside a label or ID.

flowchart TD
    A [space before] --> B  ✗
    A[no space] --> B  ✓

Fix: Don't put spaces between the node ID and its shape brackets:

A[Label]  ✓
A [Label]  ✗

Labels inside the brackets can have spaces; IDs cannot.

How to debug like a pro

1. Render incrementally. Build your diagram line by line and test after each section. The error will be obvious when only one new line was added.

2. Copy from the docs. If you're not sure about syntax, find an example in the Mermaid docs for your diagram type and adapt it.

3. Use the playground. The MermaidCreator visual editor flags syntax errors as you type and shows you exactly where the problem is.

4. Check for common typos:

   • seuqence instead of sequence
   • classDiagramm (one m)
   • flowchart vs graph (flowchart is correct for Mermaid v10+)
   • Missing [*] in state diagrams

5. Look at the browser console. If a diagram silently fails to render (no error message in your tool), open DevTools (F12) and check the console for Mermaid parser errors.

Common error messages and fixes

Error	Cause	Fix
Parse error on line X	Syntax error near that line	Check arrows, quotes, and keywords
Unexpected token	Typo or mismatched brace	Verify all blocks have matching end
Unknown keyword	Misspelled direction or diagram type	Check diagram type and direction syntax
Invalid relationship	Relationship syntax wrong for diagram type	Verify you're using the right arrow syntax

When it's not a syntax error

If your syntax is correct but the diagram still won't render:

• Clear your browser cache. Old cached Mermaid library versions can cause issues.
• Update Mermaid. If you're self-hosting, ensure you're using Mermaid v10+.
• Check your tool. Some apps (old versions of Notion, GitHub Enterprise) ship with outdated Mermaid. Paste the diagram into MermaidCreator or mermaid.live to confirm it's valid.

FAQ

Why does my diagram render on Mermaid.live but not on GitHub? GitHub and other platforms may cache an older version of Mermaid. Try clearing your browser cache, or wait 24 hours for the platform to update.

Can I use HTML tags in labels? Not directly — HTML will be escaped. Use HTML entities (<, >, etc.) instead, or try Markdown (some diagram types support it).

Why is my label cut off? Long labels may overflow if the node is too small. Try breaking the label across lines with <br/>:

["Line 1<br/>Line 2<br/>Line 3"]

Build your diagrams in the MermaidCreator playground — it validates syntax in real-time and shows you exactly where errors are, so you never get stuck again.