A diagram worked until you changed one label. Now the preview shows a parse error near an arrow that you never touched. Start with the preceding label: a missing closing quote or bracket can leave the parser waiting for the rest of a node, so the next arrow is where it finally gives up.
This guide gives you a small, working baseline and a way to isolate the failing change. The examples are deliberately short so you can compare them with your own source in the editor.
First separate the input from the renderer
A Markdown document wraps a diagram in three backticks followed by mermaid. The editor accepts the diagram inside that wrapper. Paste from flowchart TD or sequenceDiagram onward; remove the opening and closing fences if you copied an entire Markdown block.
Then check the first non-comment line. A flowchart needs a declaration such as flowchart TD. Sequence syntax starts with sequenceDiagram. Mixing the two does not combine their capabilities. A line like A --> B describes a flowchart edge; a sequence message needs its own participants and message syntax.
Use this baseline before restoring your original source:
Rendering diagram…
View Mermaid source
flowchart TD
request["Receive request"] --> valid{"Input valid?"}
valid -->|Yes| save["Save record"]
valid -->|No| reject["Return validation error"]If this renders, the editor can render a basic flowchart. That narrows the problem to your source or a feature it uses. It does not prove that every diagram type or version-specific feature is supported.
Keep identifiers stable and quote display text
Use short identifiers such as request, valid, and save. Put text intended for readers inside quotes. That keeps punctuation in a label separate from Mermaid's structural punctuation.
For example, replace the fragile label parse[Parse request (JSON)] with parse["Parse request (JSON)"]. If a label contains a double quote, simplify the label first rather than layering escapes while debugging. Once it renders, add the punctuation back using the syntax supported by your renderer.
Rendering diagram…
View Mermaid source
flowchart LR
parse["Parse request (JSON)"] --> verify["Check required fields"]
verify --> done["Return result"]The official flowchart reference documents quoted labels and the special meaning of lowercase end. Prefer a node ID such as done with a display label such as End. Do not change the end that closes a subgraph or sequence block: there it is syntax, not a node name.
Check block boundaries before changing arrows
A subgraph needs a closing end. In a sequence diagram, blocks such as alt, opt, and loop also need their own closing end. Count openings and closings from the innermost block outward. Indentation makes the structure visible, but indentation alone does not close a block.
| Symptom | First check | Useful next step |
|---|---|---|
| Error at the next arrow | Previous label has matching quotes and brackets | Replace that label with a plain word |
| Error at the end of the file | An open block or label remains | Restore one block at a time |
| Unexpected extra node | Same label uses two different IDs | Reuse one identifier for one entity |
| Arrow head looks wrong | Adjacent o or x was interpreted as edge syntax | Add spaces around the connector |
| Works here, fails in a README | The target uses a different Mermaid version or configuration | Try the smallest example in the target itself |
A chart that renders with the wrong relationship has a modeling error. A successful parse only establishes that Mermaid understood the syntax; follow every branch to check that it still describes the intended process.
Reduce a large failure without losing the original
Save the original as a .mmd file before experimenting. Work in a copy and remove styling directives, comments, and half of the unrelated branches. Keep the declaration and any required block boundaries intact. If the failure persists, reduce again. If it disappears, restore the most recent removed part in smaller pieces.
For a version mismatch, also remove newer shapes or diagram types. A basic rectangle-and-arrow version can help show whether the failure is a feature gap. Avoid changing the whole design at once: you want one change that explains the difference between a passing and failing result.
Report the smallest reproducible example
A useful report contains the reduced Mermaid source, the error text, the target application, and the renderer version if the application exposes it. Explain the expected relationship in a sentence. Remove confidential labels before sharing the source. A screenshot helps with layout failures, but source is needed to reproduce a parser failure.
When the chart renders correctly but the labels become unreadable after export, continue with the mobile layout guide. That problem needs a change in layout or output size, not another syntax fix.