Learn

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:

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:

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:

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:

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):

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.

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.