Mermaidでフローチャートを書いたのに、図が描画されず「Syntax error in text」とだけ表示される——このエラーの原因は、経験上ほぼ2つに絞られます。ノードIDに予約語（end や call など）を使っているか、エッジラベルにクォート無しで括弧を含めているかです。

筆者は複数のドキュメントで数十個のMermaid図を運用しており、あるとき一括リライトの後に図が軒並み表示されなくなったことがあります。原因を突き止めて全ブロックを総点検した経験をもとに、この記事では2大原因の見分け方と直し方、そして「1箇所直したのにまだ出ない」を防ぐ一括チェックの方法までまとめます。

Mermaid（v10系）のフローチャートでは、end / call / loop / class / click / start といった単語が構文上のキーワードとして予約されています。これらをノードIDに使うと、その1ノードだけでなく図全体がパースエラーになり、丸ごと描画されません。

特に有名なのが小文字の end です。end はsubgraphの終了キーワードなので、ノードIDにすると確実に壊れます。

NG例です（※わざと言語指定を外して掲載しています。mermaid指定にするとエラー表示になるためです）。

flowchart TD
    start[開始] --> call[API呼び出し]
    call --> end[完了]
    subgraph loop
        step1[処理1] --> step2[処理2]
    end

このコードには start call end loop と予約語が4つも入っています。対処はシンプルで、別名にリネームするだけです。call → exec、start → first、end → done、subgraph loop → subgraph phases のように置き換えます。

flowchart TD
    first[開始] --> exec[API呼び出し]
    exec --> done[完了]
    subgraph phases
        step1[処理1] --> step2[処理2]
    end

ノードIDはあくまで内部の識別子で、画面に表示されるのは [...] の中のラベルです。IDを変えても見た目は一切変わらないので、遠慮なくリネームしてください。

もうひとつの主因が、矢印につけるエッジラベル（-->|ラベル| の部分）です。ここにクォート無しで括弧（全角括弧を含む）を入れるとパースに失敗します。

NG例です（※わざと言語指定を外して掲載しています）。

flowchart TD
    user[ユーザー] -->|未登録（初回）| register[登録処理]
    user -->|登録済み| login[ログイン]

|未登録（初回）| の全角括弧が原因で図全体が落ちます。対処はラベルをダブルクォートで囲むことです。

flowchart TD
    user[ユーザー] -->|"未登録（初回）"| register[登録処理]
    user -->|"登録済み"| login[ログイン]

見落としやすいポイントとして、ノードラベル（node["ラベル（補足）"]）は気をつけてクォートしているのに、エッジラベルのクォートを忘れているケースが非常に多いです。筆者が総点検したときも、壊れていた図の大半はエッジラベル側のクォート漏れでした。「ノードは囲んだのになぜ？」と思ったら、まず矢印のラベルを疑ってください。

なお日本語ラベルそのものは問題なく使えます。括弧や特殊記号を含む場合にクォートすれば安全、と覚えておけば大丈夫です。

2大原因ほど頻度は高くありませんが、次のようなケースも報告されています。断定はできませんが、上記2つを直しても出ないときの確認候補です。

• Mermaidのバージョン差: 描画環境によって同梱されるMermaidのバージョンが異なり、片方では通る構文がもう片方で落ちることがあります
• インデントや空行の崩れ: コピペ時にインデントが崩れて解釈が変わることがあります
• Markdown側の --- との干渉: 環境によっては水平線やfront matterの --- がMermaidブロック周辺の解釈に影響するケースがあるようです

ここが実務上いちばん重要です。Mermaidのパースエラーは図単位で全滅するため、1箇所直しても同じ図の中に予約語やクォート漏れが残っていれば、図は出ないままです。「直したのに変わらない」と感じたら、修正が足りないだけの可能性が高いです。

筆者が数十個の図を一括修正したときは、次の手順で総点検しました。

1. ドキュメント内の全Mermaidブロックを機械的に洗い出す（エラーが出ている図だけを見ない）
2. 各ブロックで end / call / loop / class / click / start などの予約語ノードIDをgrepする
3. -->| を含む行を抽出し、ラベルに括弧・記号があるのにクォートされていないものを探す
4. 修正後にプレビューで全図の描画を再確認する

エラーメッセージが「Syntax error in text」としか言ってくれない以上、行単位のデバッグより「疑わしいパターンの全件スキャン」のほうが結局早い、というのが実感です。

埋め込み先のプレビューが「Syntax error in text」としか言わないのは、表示側がメッセージを丸めているためで、Mermaid のパーサ自体は落ちた行を持っています。公式の Live Editor（mermaid.live）に同じコードを貼り直すと、Parse error on line 7: のように行が特定できることが多いです（表示のされ方はバージョンで変わるので、手元の版で確認してください）。

外部に貼れないコードなら、次の3手で機械的に絞り込めます。

上2行を1回ずつ試すだけで、予約語かエッジラベルかは3手以内に確定します。1行ずつコメントアウトしていくより速く、「1箇所直しても図は出ない」という性質にも引っかかりません。

総点検は目視ではなく検索に任せます。Markdown を置いているディレクトリで、次の3本をそのまま実行してください。

# ① Mermaidブロックのフェンス行を全部数える（エラーが出ている図だけを見ない）
grep -rn --include='*.md' -e 'mermaid$' .

# ② 予約語をノードIDに使っている行
grep -rnE --include='*.md' '(^|>|\| )[[:space:]]*(end|call|loop|class|click|start|graph|subgraph|style|linkStyle)\[' .

# ③ エッジラベルをクォートせずに括弧・記号を入れている行
grep -rnE --include='*.md' '\-\->\|[^"|]*[（）()、,:;#&<>][^|]*\|' .

②③でヒットした行がそのまま修正候補です。③はクォート済みの -->|"..."| を除外してあるので、出てきた行はダブルクォートで囲めば片付きます。最後に②③の対象ブロックを①の件数と突き合わせ、未確認のブロックが残っていないかを確かめてからプレビューを開き直してください。図単位で全滅する以上、「残り1件」があると直した実感だけが得られて画面は変わりません。

Mermaidはどこでも描画されるわけではありません。ObsidianやGitHubのMarkdownプレビューはmermaidをネイティブ描画しますが、静的サイトジェネレーターなどでレンダリングさせる場合は、コードブロックの言語指定を必ず mermaid にする必要があります。言語指定を忘れると、エラーですらなく「ただのコードとして表示される」ので気づきにくいです。

逆に本記事のNG例のように、壊れたコードをあえて見せたい場合は言語指定を外す、という使い分けもできます。

なお「ASCII罫線で図を描けばエラーとは無縁では？」と思うかもしれませんが、修正のたびに罫線を引き直すのは非常に手間で、保守性ではMermaidが圧倒的に有利です。フローチャート以外にER図もテキストで管理できるので、興味があれば ER図の入門記事 も参考にしてください。

日本語自体は問題ありません。ただし括弧や記号を含む場合はクォートが必要なので、日本語ラベルは常に "..." で囲む習慣にしておくと安全です。

エッジラベル（-->|...|）のクォート漏れを確認してください。ノードラベルだけでなくエッジラベルも -->|"..."| と囲む必要があります。

end / call / loop / class / click / start あたりが代表例ですが、迷ったら別名にリネームするのが早いです。IDは表示に影響しないため、リネームのデメリットはほぼありません。

Mermaidは図単位で全滅するため、同じ図の中に問題が残っていれば表示されません。ブロック全体を再スキャンして、予約語ノードIDとクォート漏れの取り残しを確認してください。

• 「Syntax error in text」で図が丸ごと出ないときの2大原因は、予約語ノードIDとエッジラベルのクォート漏れ（特に括弧）
• 予約語（end / call / loop / class / click / start 等）は別名にリネームすれば解決。IDの変更は見た目に影響しない
• 括弧を含むラベルは -->|"..."| のようにダブルクォートで囲む。ノードラベルだけでなくエッジラベルも対象
• 1箇所直しても他に残っていれば図は出ない。全Mermaidブロックの再スキャンをセットで行う
• 静的サイトで描画させるには言語指定 mermaid を忘れずに

エラーメッセージが不親切なぶん、パターンを知っているかどうかで解決時間が大きく変わります。この記事がその近道になれば幸いです。