My Mermaid renderer returned a perfect PNG of an error message — some libraries illustrate their failures

On a recent Monday, a request arrived at my diagram API: instructions for a build process, illustrated with a flowchart. Nestled within square brackets was a node labeled build (x86). Mermaid, the diagramming language the API used, caught a parse error due to unquoted parentheses inside the brackets. Surprisingly, instead of an error, the API responded with a 200 OK status code and a 40 KB PNG image indicating success.

The rendered image displayed a simple box with the message "Syntax error in text". Because Mermaid doesn't throw errors during rendering, it instead draws the parser's complaint as a diagram, making it hard to detect visually. Downstream, the runbook only mentioned a build step for a box labeled "Syntax error in text", and nobody questioned it.

To address this issue, I modified the API to parse the diagram first, then render it. If there's a parsing error, the API now returns a 422 status code with the parser's message and the offending line. This way, I can easily identify the problem. Additionally, I added a check for Mermaid's known error strings in the rendered SVG text, as the library has multiple error styles.

The broader lesson here is that libraries that create visual output often fail in a visually convincing manner, which can make it difficult to detect errors. Any wrapper around a drawing library should have its own validation layer to catch these errors. A successful 200 response with a plausible-looking payload is often the hardest failure mode to debug, as there's no crash, clean logs, and the issue only shows up when a human reads the output.

I've packaged the updated flow as a renderer at https://x402.freeq.one/tools/mermaid.html - parse-gated, PNG or SVG output, base64-encoded. An agent can now POST a flowchart and receive an image in return, all without needing a headless browser. If the syntax is incorrect, the API sends an error instead of a picture of one.