Mermaid Syntax Error: How to Fix the Mistakes AI Makes in Mermaid Code

A Mermaid syntax error means one line of the diagram's code breaks Mermaid's rules, so the renderer stops at that line and draws nothing. In code written by ChatGPT, Claude or Gemini, check six things first: a box whose ID is end, brackets or parentheses inside a label without quotes, an arrow from the wrong diagram type, two diagram types mixed in one block, Markdown fence lines pasted with the code, and a mindmap with more than one root. Each has a one-line fix, shown below with a broken and a working example.

How do you find the line that breaks a Mermaid diagram?

Mermaid reports the first thing it cannot read. In mermaid.live, and in most tools built on Mermaid, the message starts with something like "Parse error on line 2:", repeats that line with a caret (^) under the spot, and ends with a list of what it expected and what it "got". Line 1 is the diagram type, such as flowchart TD. The "got" part is the useful clue:

If the named line looks fine, check the one above it. A mistake at the very end, such as an unfinished arrow on the last line, is reported one line further down than the code goes. Some apps hide the message and draw a picture reading "Syntax error in text" with the Mermaid version underneath; paste the code into mermaid.live to see the line number.

Why does the word "end" break a flowchart?

In a flowchart, end is a keyword: it closes a subgraph (a group of boxes). Mermaid's flowchart documentation warns that typing "end" in all lowercase letters will break the flowchart. AI models fall into it because "start" and "end" are natural names for the first and last steps. Broken: C --> end. Give the box another ID and keep the word in its label, or capitalise it:

flowchart TD
    A[Order placed] --> B{Paid?}
    B -->|Yes| C[Ship order]
    C --> done([End])

Inside a label the word is harmless: done([End]) and B[end] both render. Sequence diagrams have the same trap with a participant called end; the sequence diagram docs suggest wrapping it in quotes or brackets, and renaming it is simpler still.

Why do brackets or parentheses in a label cause an error?

Mermaid uses brackets to draw shapes: square brackets for a box, round ones for a rounded box, curly ones for a diamond. So a label such as "Send invoice (PDF)" inside a box reads, to Mermaid, like a new shape opening halfway through, and you get got 'PS'. Broken: A[Send invoice (PDF)] --> B[Mark as paid]. Wrap the label in double quotes, which the docs recommend for "troublesome characters":

flowchart TD
    A["Send invoice (PDF)"] --> B[Mark as paid]

For a double quote inside a label, use Mermaid's entity code #quot;, as in A["Click #quot;Save#quot;"]. Mindmaps are sneakier: a line like Budget (Q3) does not error at all, it quietly becomes a rounded box that says only "Q3". Quote it there too: budget["Budget (Q3)"].

Which arrows does Mermaid accept?

Each diagram type has its own arrows, and AI models borrow them across types. In a flowchart an arrow needs at least two dashes: --> (arrow), --- (line), -.-> (dotted) and ==> (thick). Text on an arrow goes between pipes, -->|Yes|, or in the middle, -- Yes -->. These all fail in a flowchart:

• A -> B (one dash)
• A --> B: Approve (a sequence-diagram style label)
• A -- Yes -> B (text with a one-dash ending)

flowchart LR
    A[Draft] --> B[Review]
    B -->|Approved| C[Publish]
    B -- Changes --> A

Sequence diagrams use a different set: ->> for a solid arrow and -->> for a dotted reply. Every message also needs a colon and some text after the arrow, as in Shop-->>Customer: Receipt; without it the diagram fails.

What happens when two diagram types get mixed?

The first line decides the rules for everything below it. Code that starts flowchart TD and then uses participant User and User->>App: Log in (sequence diagram words) fails on the first borrowed line with got 'NODE_STRING'. Decide which diagram you want and change the first line, or ask the AI to rewrite it as one type:

sequenceDiagram
    participant User
    participant App
    User->>App: Log in
    App-->>User: Welcome page

Some pairs are not mistakes. graph and flowchart start the same diagram (the docs: "Instead of flowchart one can also use graph"), and stateDiagram and stateDiagram-v2 are both valid. The Mermaid diagram types reference lists the first line for each type.

Why does Mermaid say "No diagram type detected"?

Mermaid expects the very first line to name a diagram type. Select a reply by hand instead of using the Copy code button and you also pick up the Markdown fence: ```mermaid at the top and ``` at the bottom. Mermaid then stops with "No diagram type detected matching given configuration". Delete the two fence lines, and any sentence above them, and the diagram renders. The same message appears when the type is misspelt: flowchat fails, and so does sequencediagram with a lowercase d.

Why does a mindmap say "There can be only one root"?

Mindmaps have no arrows. The hierarchy comes from indentation: the first line under mindmap is the centre, and every other line must be indented further than it. When two lines share the smallest indent, Mermaid stops with There can be only one root. No parent could be found for ("Marketing"). Broken: Launch plan and Marketing at the same indent. Fixed:

mindmap
  Launch plan
    Marketing
      Email
    Sales

Below the root, Mermaid is forgiving: the mindmap docs explain that it picks the nearest line above with a smaller indent as the parent. So when a mindmap renders but a branch hangs off the wrong parent, look for a line indented a little too far or not far enough.

How do you fix a Mermaid error with AI?

The free way is to send the error back to the assistant that wrote the code, and tell it to change nothing else:

This Mermaid code fails with the error below. Fix only what causes the error, keep every label and connection, and reply with one mermaid code block.

Error: [paste the full error message]

Code: [paste the code]

Compare the boxes before and after: a fix should not lose a step. The one-click way is Renda's Mermaid to PNG, which previews your code live for free and explains any error in plain English with its line number. Its Fix with AI button repairs the broken code for you. Fix with AI is included in Pro (£4.99 a month) or uses one of the five chat credits in a £1 Render Pack. Once the preview renders, download the PNG; five a month are free. For getting the diagram out of ChatGPT in the first place, see ChatGPT flowchart to image.

Frequently asked questions

flowchart TD
    subgraph Sales
        A[Lead] --> B[Demo]
    end