Mermaid Diagram Not Rendering? 10 Common Errors and How to Fix Them

A Mermaid diagram that will not render almost always fails for one of a small number of reasons. The error message looks cryptic (Parse error on line 4: ... Expecting 'SQE', 'DOUBLECIRCLEEND') but the cause behind it is usually a single character.

This post lists the ten failures that account for most broken diagrams, in rough order of frequency. For each one: what you see, why the parser rejects it, and the fix. If you paste the broken code into the MermanDraw editor, it marks the failing line, and for the first seven it offers a "Fix automatically" button.

1. Markdown fences pasted with the code

Symptom: Parse error on line 1, or the renderer says it cannot detect the diagram type. The code came from a chat window or a README, and the first line is three backticks followed by mermaid.

Why: the fences are Markdown, not Mermaid. GitHub and Notion strip them for you; a bare renderer does not.

```mermaid
flowchart TD
    A[Start] --> B[Finish]
```

2. Smart quotes from a docs tool

Symptom: a parse error pointing at a quoted label that looks correct. Copying from Google Docs, Word, Notion, or Slack often converts " into “ and ”.

Why: Mermaid only treats the straight ASCII double quote as a string delimiter. The curly characters are ordinary text, so the label is unquoted and the parser trips over whatever is inside it.

flowchart LR
    A["Draft"] --> B["Review"]
    B -->|"approved"| C["Publish"]

3. Unicode arrows and en-dashes

Symptom: a parse error on a line that contains an arrow. The arrow is →, or it is –> with an en-dash instead of two hyphens.

Why: word processors replace -- with a dash automatically, and some AI models output the real arrow glyph. Mermaid recognizes -->, ---, -.->, ==> and a few others, all built from ASCII characters.

flowchart LR
    Request --> Validate --> Save
    Save --> Respond

4. Parentheses, brackets, or colons inside a label

Symptom: Parse error on a node such as A[Click (here)] or B[Step 2: confirm].

Why: in a flowchart, parentheses and brackets are shape syntax. A[Click (here)] reads to the parser like a rectangle that suddenly tries to open a rounded shape. Colons, pipes and semicolons have meanings too.

Fix: wrap the label text in double quotes. Inside quotes, any character is allowed except another double quote (use #quot; for that).

flowchart TD
    A["Click (here)"] --> B["Step 2: confirm"]
    B --> C["Array[0] item"]

5. A reserved word used as a node id

Symptom: a flowchart that ends with a node called end fails, or a diagram with a node id of subgraph, style, class, click, or direction fails on that line.

Why: these words are keywords. end closes a subgraph, so C --> end is read as "close the subgraph" in the middle of an edge. Lowercase end is the one that catches people, because it is the natural name for the last step.

Fix: use a different id and put the display text in the label. The id never shows on the diagram, so finish([End]) gives you the word "End" on screen without the keyword.

flowchart TD
    start([Start]) --> work[Do the work]
    work --> finish([End])

6. An o or x right after the arrow

Symptom: the diagram renders, but an edge has a circle or a cross on its end that you never asked for. Or a parse error on an edge into a node whose id begins with o or x.

Why: --o and --x are edge styles in flowcharts (circle end and cross end). So A --oOrder, or A ---xray with no space, is read as a styled edge followed by a half-id.

Fix: put a space between the arrow and the node id, or capitalize the id. A --- oOrder still has the problem; A --- Order or A --- B[option one] does not.

flowchart LR
    A --- B[option one]
    A --- C[xray result]
    A --> D[Order placed]

7. A literal \n for a line break

Symptom: the label shows a backslash and an n, or the diagram fails to parse. The code came from a programming context where \n means newline.

Why: Mermaid labels are HTML-ish text. The escape sequence is not interpreted.

Fix: use <br/> inside a quoted label. This works in flowcharts, sequence diagram messages, and most other types.

flowchart TD
    A["First line<br/>Second line"] --> B["Single line"]

8. The wrong arrow family for the diagram type

Symptom: a sequence diagram with --> arrows renders dashed lines without arrowheads, or a class diagram with --> for inheritance shows a plain association. Sometimes the parser rejects the line outright.

Why: every diagram type has its own arrow grammar. Flowcharts use -->. Sequence diagrams use ->> for a call and -->> for a reply. Class diagrams use <|-- for inheritance, *-- for composition, and o-- for aggregation. AI models mix these up when they switch types mid-answer.

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: GET /items
    S-->>C: 200 OK

classDiagram
    class Animal {
        +String name
        +speak()
    }
    class Dog
    Animal <|-- Dog

The sequence, class and flowchart guides each list the full arrow table for that type.

9. Indentation in mindmaps, missing dateFormat in Gantt charts

Symptom (mindmap): nodes attach to the wrong parent or the parser complains about an unexpected indentation. The code was indented with tabs, or a child is indented less than its parent.

Why: mindmaps are the one Mermaid type where whitespace carries meaning. Depth is the indentation level. Mixing tabs and spaces gives inconsistent depths.

mindmap
  root((Launch plan))
    Marketing
      Landing page
      Newsletter
    Engineering
      Beta build

Symptom (Gantt): tasks fail to parse or land on the wrong dates. The chart has no dateFormat line, or the dates in the tasks do not match it.

Why: Gantt dates are parsed with the format you declare. Without a declaration the default is YYYY-MM-DD, and a task written as 11/02/2026 is rejected.

gantt
    title Sprint 12
    dateFormat YYYY-MM-DD
    section Build
    API endpoints   :a1, 2026-11-02, 4d
    UI integration  :after a1, 3d

See the mindmap guide and the Gantt guide for the remaining rules.

10. A wrong or missing diagram keyword on line 1

Symptom: No diagram type detected, or a parse error on line 1. The first line is sequencediagram (lowercase d), flow chart TD, erdiagram, or the keyword is missing because only the body was copied.

Why: the first non-empty line selects the parser. Keywords are case-sensitive: sequenceDiagram, classDiagram, erDiagram, stateDiagram-v2, flowchart, gantt, mindmap, timeline, pie.

A note on graph vs flowchart: graph TD still works and is not an error. But some newer features (markdown strings, certain shapes) only work with flowchart. If an AI gives you graph, changing it to flowchart is safe.

sequenceDiagram
    Alice->>Bob: Hello
    Bob-->>Alice: Hi

A fast debugging routine

1. Paste the code into the editor. Read the line number in the error panel, not the "expecting" list.
2. If a "Fix automatically" button appears, click it. It covers errors 1 through 4 and 7.
3. Look at the named line for a reserved word, a lowercase o/x after an arrow, or an arrow from another diagram type.
4. Still stuck? Delete lines from the bottom until it renders, then add them back one at a time. The first line that breaks it is the problem.

Working examples of every type are in the cheatsheet and the examples gallery. Starting from one that renders and editing it is faster than fixing a long diagram from scratch.

FAQ

Related

• How to generate Mermaid diagrams with ChatGPT and Claude — prompts that avoid most of these errors in the first place.
• Diagram guides — syntax, common mistakes, and FAQ for each of the 19 types.
• Where does Mermaid render natively? — when the problem is the host tool, not the code.