The Mermaid Flowchart Rendered—but the Failure Path Was Missing

A deployment flowchart went from a red parser error to a clean, exportable diagram—but the most important fix was not syntax. Mermaid Online identified two concrete code errors; the preview then exposed a missing failure path. Below is the exact before-and-after, with screenshots and the code you can adapt.

This is a small, reproducible walkthrough, not a production incident. The point is to show where the tool saves time and where a human still has to decide what the arrows mean.

The starting draft

The intended flow was simple: push to main, build an image, run smoke tests, then deploy only if they pass. Here is the deliberately flawed first version:

flowchart LR
  A[Push to main] --> B[Build image (v2.4)]
  B --> C{Smoke tests pass?} C -->|yes| D[Deploy to prod (us-west)]

Pasting this into the Mermaid syntax checker produced a parse error on line 2. The opening parenthesis in “Build image (v2.4)” was being read as Mermaid syntax rather than label text. The smallest repair was to quote the label:

A["Push to main"] --> B["Build image (v2.4)"]

That did not finish the job. The next check reached line 3 and stopped at the second C: two statements had been squeezed onto one line. Its unexpected-token clue was NODE_STRING. Splitting the edge and the yes branch onto separate lines fixed that error.

Example of the checker's line-level feedback. The full code for this walkthrough is shown above and below.

The useful lesson is that the first parser error is not necessarily the only one. Fix the reported line, run the parser again, and keep the rest of the diagram intact. A wholesale rewrite can accidentally change the process you meant to document.

A green check was not the finish line

Once the code parsed, the live preview made the larger problem obvious. The decision diamond had a yes route to production and no route for a failed smoke test. That is not a Mermaid error. A parser cannot infer your release policy.

An earlier preview of the yes-only version: syntactically valid, but the failure path is absent.

For this example, a failed test should send the team to investigate and push a fix before the build runs again. The diagram also needs to show what happens after deployment. Here is the complete tested version:

flowchart LR
  A["Push to main"] --> B["Build image (v2.4)"]
  B --> C{"Smoke tests pass?"}
  C -->|yes| D["Deploy to prod (us-west)"]
  C -->|no| E["Investigate and push fix"]
  E --> A
  D --> F["Monitor"]

The final diagram exported from the exact code above. The no route returns through a fix and a new push; the yes route continues to deployment and monitoring.

It passes the checker and renders with both branches visible. The return arrow goes to Push to main, not straight back to Build image: this example assumes a new code change is needed before retrying. If your team reruns a flaky test without a new commit, that arrow should be different. The diagram is useful only if the arrows describe the real procedure.

Getting it into the document

A valid preview is still not the same thing as a deliverable. For this case, the Mermaid Online editor’s export panel produced a 2× PNG in the Clean Docs standard style. The page reported a 2452 × 672 px file with no watermark. The same panel offers SVG, PDF, and other image formats; the core checker and standard-style exports do not require an account.

The destination decides what to keep:

• In a GitHub README that supports Mermaid, keep the source code. Reviewers can diff a changed edge and future editors can fix a label without recreating an image.
• In a slide deck or document that will not render Mermaid, use SVG when it is supported or a high-resolution PNG when compatibility matters. Keep the source beside the exported asset so the image does not become the only copy of the diagram.

The layout choice matters too. A long pipeline can become an awkward vertical strip with top-down direction. Left-to-right worked better for this example, but it made the exported image wide. A slide may need fewer nodes or two smaller diagrams rather than a tiny unreadable one.

The same steps can read very differently depending on direction and where the diagram will live.

That is the workflow Mermaid Online makes less fiddly: paste code, get a concrete parser error, inspect the rendered flow, and export a clean asset. It shortened the mechanical part of this example. It did not decide that the no branch was missing, or whether a failed test should lead to a retry, rollback, or manual review. Those remain the author's decisions.

The next time a generated diagram gives you a red banner, fix the first reported token. When it turns green, ask the harder question: what would a teammate misunderstand if they used this diagram to do the job? For more on prompt constraints and other Mermaid failure modes, there is a longer guide here.