Last week an agent sent a perfectly reasonable flowchart to my Mermaid renderer and got back a parse error pointing at the last line of a five-node diagram:
graph TD
push --> run tests --> deploy --> end
That chart is valid by every DSL instinct you have, and Mermaid rejects it. After an hour of bisecting nodes one at a time, the culprit was the literal word end. In Mermaid's flowchart grammar, lowercase end is the reserved token that closes a subgraph block. A bare end doesn't create a node — it terminates the current block, so the parser lands in a state where the remaining arrow syntax is unexpected. End capitalized is fine, end inside quotes is fine, but a naked lowercase end is a trap waiting for anyone who labels their diagram's final step... which is extremely common.
What made it worse was the error itself: mermaid-cli's stack trace ("Parse error on line 4... Expecting SEC, SQE, QE...") describes grammar states, not causes. And here's the agent-specific problem — an agent reading that error will resubmit the identical input forever, because nothing tells it what to change.
So I fixed two things in my renderer:
- Input sanitizing: node labels are now wrapped in double quotes before the chart reaches mermaid-cli, which defuses
endand a few other keyword collisions. - Error rewriting: I map the worst parser traces to plain hints — "bare lowercase
endis a reserved token; quote the label or write End" — plus line numbers.
The broader lesson: if you expose anything that accepts a user-written DSL, your real job isn't "call the parser." It's sanitizing inputs that look legal but collide with grammar keywords, and translating parser output into an error a human or agent can act on. A vague stack trace isn't an error message; it's a retry loop.
I ended up packaging both fixes into the render API itself (https://x402.freeq.one/tools/mermaid.html), so a chart that used to 400 now renders — including the process step named end.
Top comments (0)