Mermaid diagram not rendering in a GitHub issue: what to check

You pasted a Mermaid block into a GitHub issue, clicked Comment, and where the diagram should be there is a grey box.

The bot behind this site draws Mermaid diagrams on some of the issues it restates, so we have spent more time than most looking at that box. This page is the checklist, in the order worth working through it, and the failures no amount of escaping will fix.

"Unable to render rich display"

That grey box means the block was recognised as Mermaid and then did not come back as a picture, which is usually a parse failure in your source. If there is an error line printed under it, read that first: it will often name a character or a line number, and it is the only free information you are going to get. If the same block renders in the Mermaid live editor and the box on GitHub carries a JavaScript error instead of a syntax one, the fault is on GitHub's side and nothing you do to your diagram will move it.

Then open the source before you change anything. The difference between a working diagram and a broken one is usually one character, and the rendered view hides it. Click Edit on the comment, or open the issue body for editing, and read the raw Markdown.

If there is no error box at all, and the problem is that the diagram came out wrong rather than missing, the escaping sections below are not your answer. Skip to It rendered, and it is still wrong.

The usual cause: the arrow head has been escaped

The line says --> where it needs to say -->.

Something between you and the comment box HTML-escaped the angle bracket. A form that escapes input, a copy and paste out of rendered HTML, a templating layer, or a language model told to escape angle brackets so that node labels do not break the parser, which then applies that rule to the whole line instead of to the label. The arrow head is the casualty.

Every arrow in the language fails the same way, so check the other link types before you decide this is not your problem: ->> and -->> in sequence diagrams, -.retry.-> for a labelled dotted link, ==> for a thick one, -->|every 30s| for an edge label, and the class diagram relations <|-- and <|.., which break at the tail rather than the head.

Fixing it without breaking your labels

Do not run a blanket replace of > to >. That will also strip the escaping out of A[Value > 10], which is the one place the escaping was correct, and you will trade one error box for another.

If you are scripting a repair, the simplest rule that works is adjacency. Unescape an escaped > only when the character immediately before it is link punctuation: a hyphen, an equals sign, a dot, a pipe, or another angle bracket. Unescape an escaped < only when the character immediately after it is one of those. Leave everything else exactly as it was.

Know what that rule does not buy you. A[Value > 10] survives because a space sits in front of the entity, not because the rule knows it is inside a label. It has no bracket awareness at all, so a label written as A[Retry->10] would be unescaped and would then break. Doing this by hand, use the safer version: change entities that touch link punctuation, and leave anything inside square brackets, round brackets or quotes alone.

One more detail, and it is the one that makes people think the fix did not work. In ->> the second entity is not adjacent to link punctuation until the first one has been decoded, so a single pass over the line leaves you with ->> and a diagram that still fails. Run the replacement again until nothing changes. Two passes clear every arrow in the syntax, because no link token stacks three angle brackets; give the loop a small cap anyway, so a bug in it cannot spin forever.

The rule underneath all of this: escape labels, never links

Escaping belongs inside node labels, edge labels and subgraph titles. Inside a label, replace ; with &#59;, < and > with < and >, and brackets with ( and ). Outside a label, every character of -->, ->>, -.->, ==>, <|-- and <|.. stays literal. Quote a subgraph title that contains anything unusual: subgraph "Bug Fixes".

It rendered, and it is still wrong

These three are not render failures. There is no error box, and the Mermaid parsed. The first is a renderer difference that damages a label quietly. The other two are judgements rather than limits GitHub imposes, and they are the reasons a diagram that parsed perfectly is still no use to the person reading the issue.

A br tag in a node label

You wanted two lines in one box, so you wrote A[User Selection<br>0/1/2]. Mermaid treats that as a line break and on github.com it normally works, so do not go looking here first if what you have is an error box. The failure it does produce is quiet: the tag is dropped during sanitising and the two halves run together as User Selection0/1/2, with no space and no warning. If your diagram rendered but a label reads like two words jammed into one, this is why.

Two situations still bite. GitHub Enterprise Server ships an older Mermaid build than github.com does, and the older build strips the tag instead of breaking the line. And a file you have not touched can keep serving a cached render from before the rendering pipeline changed underneath it, which a hard refresh will not clear because the stale copy is on the server. Pushing any commit that changes the file is the only lever you have, and for a file you do not own there is none.

If you generate diagrams, replace the tag with a space before posting. If you are editing by hand, split the label into two nodes. That reads the same whichever Mermaid build renders it.

The same goes for bullet points and lists inside a node. Short plain text only.

Too many nodes

An issue comment is a narrow column. A diagram with thirty boxes in it either scrolls sideways out of that column or shrinks until the labels are unreadable, and a reader on a phone gets the worse of the two. Keep it to about a dozen nodes, and if the true picture is bigger than that, draw the part that matters and describe the rest in a sentence.

There is an uncomfortable version of this worth saying out loud. If the honest diagram of your problem needs thirty nodes, the usual reason is not that the system is complicated. It is that the issue contains more than one problem, and the diagram is the first thing to notice.

Custom fill colours

A line of style fill:#f9f looks fine in the editor where you wrote it. Custom colours often come out with poor contrast for somebody else, and you have no way to check that from your side. If you want a node to stand out, put a leading symbol in the label instead: a red circle for a failing state, a warning triangle, a tick for success, a chart for data, a pair of arrows for a process. It survives whatever theme the reader is using.

If none of that applies, two cheap checks

Check the fence. It opens with the bare word mermaid after the backticks, and the indentation has to stay inside whatever block it sits in. A fence nested under a list item does render, but go four or more spaces past that item's own text column and Markdown turns the whole thing into an ordinary indented code block before the diagram renderer ever sees it. You get plain text where a picture should be, which looks like a rendering failure and is not one.

And check the surface. Everything on this page was checked in issues and issue comments. A block that renders in an issue is not proof about the next place you paste it, so test it there before you rely on it.

Whether the diagram was worth posting at all

A diagram that renders and adds nothing is still a failure, just a quieter one.

A diagram is for structure that prose carries badly: a sequence of calls, a state machine, a set of relationships. Most issues have none of those, and a picture of a two-step bug is padding. Rules worth holding to: a diagram only where it carries structure, at most one per message, and never a repeat of one already posted in the thread. Two or three near-identical pictures on the same issue is what you get without them.

The last rule matters most and is the easiest one to break in good faith. A diagram supports a bug report, it does not replace one. The substitution a diagram most tempts people into is using it instead of reproduction steps, and a flowchart of how you believe the system works is not evidence of what it did. It is a drawing of your theory. If the choice is between the diagram and the steps, post the steps.