Gotchas

Common Mermaid parser traps that waste time. Check here first when a diagram that “should work” does not render.

The end keyword

The word end (lowercase) is reserved in Mermaid. Using it as a node label or in text without quoting breaks the parser silently.

Broken:

flowchart TD
    A[Start] --> B[end]

Fixed:

flowchart TD
    A[Start] --> B["End"]

Quote labels that contain end, or capitalize it. This applies across all diagram types, including sequence diagram notes and state labels.

Accidental edge markers in flowcharts

In flowcharts, o and x at the start of a node name right after a --- edge create circle or cross markers instead of a normal connection.

Broken (creates a circle marker):

flowchart LR
    A---objectStore[Object Store]

Fixed:

flowchart LR
    A --- objectStore[Object Store]

Add a space before the node name, or use --> instead of ---.

Special characters in labels

Parentheses, brackets, pipes, and curly braces inside labels conflict with Mermaid’s node shape syntax. Always quote labels with special characters.

Broken:

flowchart TD
    A[User (Admin)] --> B

Fixed:

flowchart TD
    A["User (Admin)"] --> B[Next]

Use double quotes around any label containing (, ), [, ], {, }, or |.

Participant ordering in sequence diagrams

Participants appear in the order they are first mentioned. If you want a specific left-to-right order, declare all participants explicitly at the top.

Unpredictable order:

sequenceDiagram
    B->>A: Hello
    A->>C: Forward

Controlled order:

sequenceDiagram
    participant A as Client
    participant B as Server
    participant C as Database
    B->>A: Hello
    A->>C: Forward

Architecture-beta: limited renderer support

The architecture-beta diagram type is an experimental Mermaid feature. It fails to parse in many client-side renderers and static site generators (including Astro with client-side mermaid). Use flowchart with subgraph instead for service topology diagrams.

Unreliable (architecture-beta):

architecture-beta
    service ad(server)[AD]
    service entra(cloud)[Entra]
    ad:R --> L:entra

Reliable alternative (flowchart with subgraph):

flowchart LR
    subgraph onprem["On-Premises"]
        ad[AD]
    end
    subgraph cloud["Cloud"]
        entra[Entra]
    end
    ad --> entra

Subgraph scoping in flowcharts

Nodes defined inside a subgraph block are scoped to it. Referencing a node from another subgraph requires using the full node ID, not a label.

flowchart TD
    subgraph A[First Group]
        a1[Node 1]
    end
    subgraph B[Second Group]
        b1[Node 2]
    end
    a1 --> b1

Gotcha: The end keyword that closes a subgraph is one of the few places where bare lowercase end is valid and required.

Comments

Use %% for comments. They must be on their own line. Inline comments after diagram syntax can cause parse errors in some renderers.

flowchart TD
    %% This is a comment
    A[Start] --> B[Finish]