MermaidSyntaxTroubleshootingLearningDebugging

Mermaid syntax mistakes beginners make (and how to fix them)

June 30, 20267 min readThe MermaidCreator team

You write a Mermaid diagram. It looks perfect in your mind. You paste it into your editor and... nothing renders. Or it renders halfway and breaks. The browser console shows "Mermaid rendering failed," but the error message is cryptic.

Syntax errors are the fastest way to get stuck with Mermaid. The good news: they're predictable. This guide walks through the 10 most common mistakes beginners make, why they happen, and how to fix them—so you can debug your diagrams in seconds, not hours.

1. Missing or mismatched quotes in node labels

The mistake:

flowchart TD
    A[Unquoted Label]
    B["Quoted Label"]
    C["Quoted with spaces inside"]

The error: Mermaid: Syntax error on line... (depending on what's inside the brackets).

Why it breaks: Unquoted labels with special characters, hyphens, or certain punctuation confuse the parser. It thinks the hyphen is a syntax operator, not part of the text.

The fix: Quote all multi-word labels:

flowchart TD
    A["Send verification email"]
    B["Check inventory - reorder if low"]
    C["Status: Active"]

Rule of thumb: If your label has spaces, punctuation, or special characters, quote it. Single-word labels are fine unquoted.

2. Forgetting node IDs in arrows

The mistake:

flowchart TD
    ["User login"] --> ["Verify password"]

Why it breaks: Arrows need to reference node IDs, not the labels themselves. Mermaid sees ["User login"] as a definition (a node with no ID), then tries to use it as an ID in the arrow—confusion.

The fix: Define nodes with IDs first, then arrow between them:

flowchart TD
    A["User login"]
    B["Verify password"]
    A --> B

Or, use the shorthand (combine definition + arrow):

flowchart TD
    A["User login"] --> B["Verify password"]

Rule of thumb: Every node needs an ID (single letter, word, or number). Use IDs in arrows; save the label (the bracketed text) for display.

3. Syntax error: using wrong bracket type

The mistake:

Different bracket types mean different shapes in flowcharts. Mixing them up:

flowchart TD
    A{Diamond shape}      # Wrong: this is for decisions
    B["Rectangle shape"]
    C{Check status?}      # Correct: decision
    D[Process step]       # Wrong: should be ["..."]

Why it breaks: [text] is a rectangle, {text} is a diamond, (text) is a circle, [/text/] is a parallelogram. Using the wrong type makes the parser confused.

The fix: Match the bracket to the shape you want:

Shape	Bracket	Example
Rectangle	`["..."]`	`A["Process data"]`
Diamond (decision)	`{...}`	`B{Valid?}`
Circle (start/end)	`(((...)))`	`C(( Start ))`
Parallelogram (input)	`[/.../ ]`	`D[/ Input /]`
Stadium (rounded)	`([...])`	`E(["Flow step"])`

4. No spaces around arrow operators

The mistake:

flowchart TD
    A-->B
    C-->|Label|D

Why it breaks: Mermaid's parser prefers spaces around -->, ---, and -.->. While it often works, inconsistent spacing can confuse the parser, especially with edge labels.

The fix: Always add spaces:

flowchart TD
    A --> B
    C -->|Label| D
    E -.-> F

5. Forgetting commas or semicolons in lists

The mistake:

tags:
  - Mermaid
  - Flowchart
  - Tutorial

In YAML frontmatter (blog post headers), forgetting the hyphen or comma:

tags: [Mermaid Flowchart Tutorial]
# or
tags: Mermaid, Flowchart, Tutorial

Why it breaks: YAML is strict. A list needs - item or [item1, item2] format.

The fix: Use proper YAML list syntax:

tags:
  - Mermaid
  - Flowchart
  - Tutorial

Or inline:

tags: [Mermaid, Flowchart, Tutorial]

6. Using invalid diagram type

The mistake:

diagram TD
    A["..."]

diagram isn't a type. Common typos: chart instead of graph, flow instead of flowchart.

The fix: Use the correct diagram type:

flowchart TD
    A["..."]

Valid types: flowchart, sequenceDiagram, stateDiagram-v2, erDiagram, gantt, pie title, graph, gitGraph, mindmap, timeline, sankey-beta.

7. Mixing graph direction syntaxes

The mistake:

graph LR
    A --> B
    B --> C
    graph TD
      D --> E

Redefining direction mid-diagram confuses Mermaid.

The fix: Pick one direction at the top and stick with it:

flowchart LR
    A --> B
    B --> C
    D --> E

Direction options: TD (top-down), LR (left-right), DU (bottom-up), RL (right-left).

8. Forgetting subgraph closure

The mistake:

flowchart TD
    subgraph A ["Group A"]
        B["Node B"]
        C["Node C"]
    subgraph D ["Group D"]
        E["Node E"]
    # Missing 'end' before opening a new subgraph

Why it breaks: Subgraphs nest. If you don't close the first with end, the parser thinks everything after belongs to it.

The fix: Close every subgraph with end:

flowchart TD
    subgraph A ["Group A"]
        B["Node B"]
        C["Node C"]
    end
    
    subgraph D ["Group D"]
        E["Node E"]
    end

9. Using reserved words as node IDs

The mistake:

flowchart TD
    start["Begin"]
    end["Finish"]
    start --> end

start, end, and a few others are reserved in some diagram types (e.g., sequenceDiagram reserves par, alt, loop).

Why it breaks: The parser thinks end is a keyword, not an ID.

The fix: Use different IDs:

flowchart TD
    A["Begin"]
    B["Finish"]
    A --> B

Or use longer IDs:

flowchart TD
    start_node["Begin"]
    end_node["Finish"]
    start_node --> end_node

10. Incorrect edge label syntax

The mistake:

flowchart TD
    A{Decision?}
    B["Yes path"]
    C["No path"]
    A --> B ["Yes"]
    A --> C ["No"]

The bracket placement is wrong. Edge labels go before the arrow target.

The fix: Use pipes for edge labels:

flowchart TD
    A{Decision?}
    B["Yes path"]
    C["No path"]
    A -->|Yes| B
    A -->|No| C

Syntax: A -->|label| B (label between pipes before the target).

Debugging workflow

When your diagram fails to render:

Check the browser console — Copy the error message.
Count brackets — For every [ there's a ]; for every { there's a }; for every subgraph there's an end.
Verify diagram type — Is it flowchart, sequenceDiagram, stateDiagram-v2, etc.?
Check node IDs — Are all IDs used in arrows actually defined?
Validate quotes — Multi-word labels are quoted; single-word labels are optional.
Test in the editor — Use MermaidCreator's editor for instant feedback; fix one error at a time.

Common error messages and fixes

Error	Means	Fix
`Syntax error on line N`	Parser hit a character it didn't expect	Check brackets, quotes, reserved words on that line
`Unexpected token`	Invalid syntax at a specific point	Check arrow syntax, subgraph nesting, node definition
`Cannot find node with ID X`	Node X is referenced in an arrow but never defined	Add `X["Label"]` before using it in an arrow
`Diagram type not recognized`	Wrong diagram type keyword	Use `flowchart`, `sequenceDiagram`, etc.
`Rendering failed`	Mermaid couldn't render (usually a parsing error)	Simplify the diagram; test smaller pieces first

Example: before and after

Broken diagram:

flowchart TD
    Start(Start Process)
    CheckStatus{Is status valid}
    SendEmail[Send email notification]
    End(( End ))
    
    Start-->CheckStatus
    CheckStatus--Yes-->SendEmail
    CheckStatus--No-->End
    SendEmail-->End

Fixed diagram:

flowchart TD
    A(( Start ))
    B{"Is status<br/>valid?"}
    C["Send email<br/>notification"]
    D(( End ))
    
    A --> B
    B -->|Yes| C
    B -->|No| D
    C --> D

Changes made:

Node IDs (A, B, C, D) for clarity.
Quoted multi-word labels: ["Send email<br/>notification"].
Used (( ... )) for start/end circles (two sets of parens).
Fixed arrow labels: -->|Yes| instead of --Yes-->.
Added <br/> for line breaks in long labels.

FAQ

Why does my diagram sometimes work and sometimes fail?
Mermaid's parser is forgiving in some cases but strict in others. Inconsistency (sometimes spaces, sometimes not) can flip between working and broken. Be consistent in your syntax.

Can I test my diagram syntax without rendering?
Yes. Use the MermaidCreator editor—it renders live as you type and shows errors instantly.

Is there a Mermaid linter?
Not officially, but you can use Prettier (with a Mermaid plugin) or run diagrams through the MermaidCreator editor to catch errors.

What if my error message is still cryptic?
Simplify your diagram—remove half the nodes, test, then add back. Start with a 3-node diagram and build up. This narrows down exactly which line causes the issue.

Where can I find the full Mermaid syntax reference?
The official docs are at mermaid.js.org. Use them alongside MermaidCreator's visual editor for the best learning experience.

Master these 10 mistakes and you'll spend your time creating, not debugging. Start with small diagrams, test in the MermaidCreator editor, and build up to complex models with confidence.

Troubleshooting