Skip to content
MermaidViewer

Fix a Mermaid syntax error

Fix a Mermaid syntax error: quotes, the word end, arrows, dates and the other mistakes behind 'Syntax error in text'.

By MermaidViewer editorsPublished Updated

"Syntax error in text" and "Parse error on line X" are the messages every Mermaid user sees eventually. The good news: almost all errors come from a handful of mistakes. The MermaidViewer editor highlights the failing line, and the AI Fix button can repair broken code automatically — but it's worth knowing the usual suspects.

1. Special characters in labels

Parentheses, brackets, quotes, colons and semicolons have meaning in Mermaid. Wrap labels that contain them in double quotes.

mermaid
%% Broken
flowchart LR
    A[Call api(v2)] --> B

%% Fixed
flowchart LR
    A["Call api(v2)"] --> B

2. Lowercase end as a node

end closes subgraphs and blocks. A node called end breaks the diagram. Use End, finish or ["end"].

3. Missing or misspelled diagram keyword

The first line must be a valid keyword: flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt, pie, mindmap and so on. Keywords are case-sensitive: sequencediagram fails.

4. Wrong arrow syntax for the diagram type

Each diagram has its own arrows. --> works in flowcharts, but sequence diagrams need ->> or -->>, and ER diagrams need cardinality markers like ||--o{.

5. Unclosed blocks

Every subgraph, loop, alt, opt, par, rect and composite state needs a matching end. Indent nested blocks so missing ends are easy to spot.

6. Indentation in mindmaps and kanban

Mindmaps, treemaps and kanban boards use indentation for hierarchy. Mixing tabs and spaces or inconsistent indents creates wrong trees or errors. Use two spaces consistently.

7. Spaces in ids

Node ids cannot contain spaces. Use userService[User service], not User service --> DB.

8. Colons in sequence messages and Gantt tasks

In sequence diagrams the first colon separates the arrow from the message text; in Gantt charts the colon separates the task name from its metadata. Avoid extra colons in names or escape them with #58;.

9. Invalid dates in Gantt charts

Dates must match dateFormat. If you declare dateFormat YYYY-MM-DD, a date like 01/02/2026 fails.

10. Unsupported diagram type for the renderer

Newer types (architecture, radar, treemap, kanban) need a recent Mermaid version. They work in MermaidViewer, but older platforms may show an error. Export an image for those platforms.

11. Smart quotes and invisible characters

Copying from Word or Slack can insert curly quotes (“ ”) or non-breaking spaces. Replace them with straight quotes and normal spaces.

12. Comments in the wrong place

Comments must start with %% on their own line. Inline comments after code can break parsing in some diagram types.

Let AI fix it

Paste the broken diagram into the editor and click AI → Fix syntax. The AI reads the error message and your code, repairs the syntax and keeps your structure. You can review the fix before accepting it.

Quotes, before and after

A mermaid syntax error on a label is usually a character that is also punctuation in the grammar. Parentheses, brackets, and colons start shapes or messages. The parser then reports a line that looks like plain English.

This version puts parentheses in an unquoted rectangle. It fails, so it is shown as text rather than as a diagram:

text
flowchart LR
    A[Call api(v2)] --> B[Save result]

Quote the label. The id stays outside the quotes, where it remains a single token. The words inside the quotes are allowed to look like syntax because the parser treats them as a string.

Mermaid diagram
mermaid
flowchart LR
    A["Call api(v2)"] --> B["Save result"]
Open in the live editor

Use the same quotes for a slash, a question mark, or a colon in a flowchart label: Q{"Retry after 30s?"}. If the label needs a literal double quote, write #quot; inside the string. Curly quotes copied from a document are a different failure with the same symptom. Replace them with straight " characters.

Quote the smallest span you can. A["Call api(v2)"] keeps the id A outside the string. Quoting the whole statement hides the arrow from the parser and creates a new error. The themes guide is irrelevant here. Nothing is wrong with the color. The string never closed.

A subgraph that swallows the rest of the file

end closes the nearest subgraph. It is not a node id. A chart that tries to finish on a node named end, and that also forgets a closer, produces a mermaid syntax error far from the line you think is wrong. The parser runs out of diagram, or it closes early and then chokes on the next statement.

text
flowchart TD
    subgraph Browser
        A[Reset form] --> B[Submit]
    subgraph Server
        C[Check token] --> end
    end

Two problems sit in that text. Browser is never closed, because the only end was consumed by Server. And end was meant to be a step, so the Server group lost its last node. Name the step Finish and give it the label you want readers to see. Close both groups.

Mermaid diagram
mermaid
flowchart TD
    subgraph Browser
        A[Reset form] --> B[Submit]
    end
    subgraph Server
        C[Check token] --> Finish["End"]
    end
    B --> C
Open in the live editor

Indent the body of each subgraph by four spaces so a missing end is obvious in the diff. The indent doesn't create the group. The end does. When you nest a third group, close the inner one before the outer one, the same way you close brackets. The flowchart guide uses this shape for a deploy pipeline. Copy the closers from there if you are unsure which end belongs to which box.

A missing colon on a sequence message

In a sequence diagram the colon splits the arrow from the message. User->>API: POST /reset means the arrow is ->> and the text is POST /reset. Leave the colon out and the parser doesn't know where the message starts. You get a mermaid syntax error on that line even though the arrow looks right.

text
sequenceDiagram
    participant User
    participant API
    User->>API POST /reset
    API-->>User: 202 Accepted

Put the colon immediately after the destination. Spaces around it are fine. Extra colons inside the message are usually part of the text, because the first colon is the separator. The one that breaks a block is a colon inside a keyword label such as alt or loop, where Mermaid may read the colon as the start of a message. Rephrase alt token: expired to alt token expired, or write the colon as #58; if you must keep it.

Mermaid diagram
mermaid
sequenceDiagram
    participant User
    participant API
    User->>API: POST /reset
    API-->>User: 202 Accepted
Open in the live editor

The arrow shapes still have to match the diagram. --> is a flowchart arrow. Sequence messages use ->> for a solid arrow and -->> for a dashed reply. A colon won't rescue the wrong arrow. Participants can be implicit, but declaring them, as this fix does, keeps the order stable when you add a third actor. More of that syntax is on the sequence diagram reference and in the sequence tutorial.

A Gantt date that doesn't match the format

Gantt charts declare dateFormat and then every date has to match it. The error looks like a mermaid syntax error on the task line. The task name is often innocent. The date is in another country's order, or it includes a time the format didn't mention.

text
gantt
    title Migration
    dateFormat YYYY-MM-DD
    section Data
    Export rows :a1, 04/06/2026, 3d

YYYY-MM-DD means year, month, day, with hyphens. 04/06/2026 doesn't match, and it is ambiguous even to a person. Write the ISO date. A duration such as 3d is allowed after a valid start. after a1 is allowed when the task has an id.

Mermaid diagram
mermaid
gantt
    title Migration
    dateFormat YYYY-MM-DD
    section Data
    Export rows :a1, 2026-04-06, 3d
    Load staging :a2, after a1, 2d
Open in the live editor

A colon in the task name breaks the same line, because the colon also introduces the metadata. Design: API :a1, 2026-04-06, 3d splits too early. Name it Design API, or escape the colon as #58;. Keep one dateFormat per chart. Mixing YYYY-MM-DD tasks with DD/MM/YYYY tasks means half the file fails even after you fix the first row. The Gantt reference lists the tokens the format string accepts.

Weekends and milestones are a second pass. Get one task rendering with a date you can point at on a calendar. Then add excludes weekends or a milestone. A milestone with a three-day duration is a different bug. Set the duration to 0d when the event is a point in time.

Month and day tokens are case-sensitive in the format string. YYYY-MM-DD is not the same pattern as YYYY-mm-dd. If you change the format, change every task in the file in the same edit. A single old row will keep the chart broken, and the line number will be that row, not the dateFormat line you just touched.

A mindmap indent that re-parents a node

Mindmaps, and a few other types, use indentation as structure. A mermaid syntax error is one outcome. A worse outcome is a diagram that renders with the wrong parent and no error at all. The reader trusts the tree. The tree is a lie.

This text mixes widths. Dates sits at an indent that doesn't match Plan or Scope. API is shoved further right than UI. Depending on the exact spaces, Mermaid either rejects the file or hangs Dates off the root.

text
mindmap
  root((Launch))
    Plan
      Scope
     Dates
    Build
        API
      UI

Pick two spaces per level and use them everywhere. The root is the least indented node. Each child is two spaces deeper than its parent. Don't use tabs. A tab counts as a different width than the spaces on the next line, and the parent changes.

Mermaid diagram
mermaid
mindmap
  root((Launch))
    Plan
      Scope
      Dates
    Build
      API
      UI
Open in the live editor

Scope and Dates are children of Plan. API and UI are children of Build. Plan and Build are children of Launch. If you wanted Dates under Launch, put it at the same indent as Plan, on purpose, and look at the rendered tree before you commit. The mindmap reference shows the shapes you can wrap around a node. Add shapes after the indent is stable. A shape on a mis-parented node hides the bug in decoration.

What to do with the next error

Read the line number, then read the line above it. Unclosed quotes and unclosed subgraphs are reported where the parser gives up, which can be the end of the file. The defect is the earlier line that opened the string or the group.

Paste the block into the editor. The preview marks the failure without a commit cycle. If you can't see it, run the same text through npx -p @mermaid-js/mermaid-cli mmdc and use the exit code in CI. The export guide has a workflow you can copy.

Change one thing and render again. Fixing quotes, end, a colon, a date, and an indent in one edit makes the next error unreadable. When the text is valid and the picture is still the wrong story, stop chasing syntax. The parser has done its job. Edit the labels, or ask the AI generator to repair the line using the error text, then read the repair. An automatic fix that quotes the wrong half of the line will parse and still say the wrong thing.

Keep the broken copy in the commit message or in a scratch file until the fix renders. It is tempting to "clean up" the bad line before you understand it, and then you can't tell which character mattered. The five pairs on this page are the ones to compare against first: quotes, end, the sequence colon, the Gantt date, the mindmap indent. If your line doesn't resemble any of them, check the keyword on line 1. A misspelled sequenceDiagram or a flowchart arrow inside an ER diagram fails before any of these local fixes apply.

Frequently asked questions

What does 'Syntax error in text' mean in Mermaid?

Mermaid could not parse your diagram. The message usually comes with a line number; check that line for special characters, wrong arrow types, missing end keywords or a misspelled diagram keyword.

Can AI fix my Mermaid code?

Yes. MermaidViewer's AI Fix sends your code and the parser error to an AI model that returns corrected Mermaid syntax, which you can accept or discard.