Drawio Troubleshooting
Shape Changes After Style Updates
An mxCell style mixes bare style names (rhombus, text, swimlane) with key=value entries. A dictionary rebuilt from only entries containing = silently drops the shape or text-only style: diamonds become rectangles and labels gain borders. Preserve bare tokens and patch only requested keys. Verify both a diamond and a standalone label after serialization, then re-export and inspect; valid XML alone does not catch this regression.
Troubleshooting Table
| Issue | Solution |
|---|---|
エージェントが生成した .drawio を draw.io / VS Code 拡張が開けない。先頭が <mxfile になっている |
構造タグまで HTML エスケープされて書き出されている。一括デコードで直すと value 内の <br> まで実体化して XML が壊れるので、<br> を一時マーカーへ退避 → [System.Net.WebUtility]::HtmlDecode → マーカーを戻す → BOM なし UTF-8 で書き戻す。生成直後に先頭行が <mxfile で始まるか、[xml] へキャストできるかを確認すると 1 手で気づける |
validate_drawio.py が UnicodeEncodeError: 'cp932' codec can't encode character で落ちる |
Windows の PowerShell で Python の stdout をパイプすると encoding が cp932 に変わり、スクリプトが出す ✅ / ⚠️ を書けなくなる。図の不備ではないので、$env:PYTHONUTF8="1" を先に設定して再実行する。パイプせず直接実行すれば再現しない |
| Blank in draw.io | Check content attribute |
| Edges not visible | Verify node IDs |
| Icons missing | Enable Azure/AWS shapes (+ More Shapes → Azure / AWS) |
| Text overlaps near outer frame | Inset top note/callout boxes 16-24px from the panel border, increase box height, wrap to 3-4 lines. Review at actual embed width. See style-guide.md Top Callouts / Note Boxes |
| README image only links to source | Generate *.drawio.svg and embed that instead of linking only to *.drawio |
| SVG is viewable but hard to edit later / user says the diagram is not editable | Keep a paired *.drawio source as the editable SSOT and use SVG as delivery output, not as the only source. Confirm the user is opening the *.drawio, not a plain preview SVG/PNG. If editability was requested, remove or de-emphasize preview-only links and make the .drawio the primary deliverable |
VS Code says a .drawio.svg or .drawio file cannot be opened even though it exists |
CLI で書き出した SVG は --embed-diagram が無いと mxfile が落ち、draw.io が「図面ファイルではありません」と言う。まず .drawio.svg に mxfile の文字列が含まれるか確認し、無ければ --embed-diagram を付けて再書き出しする。次に Check whether the file is actually a plain SVG misnamed as .drawio.svg; if so, rename to *.svg. If path resolution still stale, create a short alias filename and repoint links |
| Local Markdown preview does not show the expected diagram | Export *.png from .drawio and use that in the draft preview. Keep .drawio + *.drawio.svg pair for final delivery |
| Too many crossing arrows | Keep the primary decision chain in the main vertical lane; send terminal outcomes sideways, not intermediate decision nodes. Align source/target y to make edges horizontal; avoid routing branch outcomes back to earlier nodes or a distant shared sink. A passing mxCell validator proves structure, not visual routing: after adding or moving an edge, re-export the delivery asset for the target medium (SVG for web, PNG or the final PDF for print) and inspect it. For peer nodes feeding one target, use distinct vertical lanes or explicit exit / entry ports instead of relying on automatic orthogonal routing. See style-guide.md Edge Crossing Prevention |
| Edge label overlaps a decision diamond | For a decision branch, leave the edge value empty. Route the connector with explicit points, then use a standalone text cell for the branch label outside both nodes and clear of arrowheads. Review at the target embed width. |
| Standalone relationship label looks attached to the wrong node | Center the label over or immediately beside its connector, with a small visual gap from the line. Do not place it in a node's surrounding whitespace; re-export and inspect it at the target embed width. |
| Legend inside a container | Move legend outside the outermost box. See style-guide.md Nested Containers |
| Diagonal edge crosses a box | Move annotation boxes below diagonal endpoints. See style-guide.md Flow Diagrams |
value 内の <word> プレースホルダが消える / 表示が崩れる (例: ~/.copilot/pkg/<platform>/<version>/ が ~/.copilot/pkg/// になる) |
drawio は value を HTML として解釈する。<...> は未知タグとして除去される。<> の代わりに [platform] / [version] / {var} などの角括弧プレースホルダを使うのが安全。エスケープで通すなら層を区別する。GUI 入力は draw.io が serialize するので literal のまま打つ。mxCell の internal value は <word>。スクリプトが raw XML 属性を直接生成する場合は &lt;word&gt; と 2 重にする（1 重だと XML デコードで < へ戻り、html=1 の HTML 解釈で未知タグとして消える） |
バッククォート付きトークン (例: `/research`, `/fleet`) がタイトルで数式化して f≤et のように崩れる |
drawio は ` で囲まれた範囲を MathJax として render することがある（特に \ を含むと LaTeX シンボル化）。**タイトル / ラベルではバッククォートを使わず**、強調はテキスト装飾 (<b>) か別フォントで表現する |
インフォグラフィック HTML→PNG で /fl /fi 等が ≤ 風グリフに置換される |
JetBrains Mono のリガチャ（合字）が原因。CSS に font-feature-settings: "liga" 0, "clig" 0, "calt" 0; font-variant-ligatures: none; を付けて無効化。ヒット箇所はコマンド表記が多いので .cmd / .mono クラスに当てる |
| Title duplicated in PDF/HTML | Remove title mxCell from diagram; let the document layer handle captions |
| PNG export blurry or cropped | Use draw.io --export --format png --scale 2 instead of browser screenshot. See style-guide.md Export for PDF Pipelines |
| 直交ルータが斜めのエッジを勝手に折り曲げる / 本線と重なる | edgeStyle=orthogonalEdgeStyle は始点と終点が斜め関係のエッジを自動でエルボー展開する。経路が再現しないうえ、展開した最初の脚が本線と重なったり、箱の外へ短い横棒が飛び出したりする。斜めの直線を出したいなら edgeStyle=orthogonalEdgeStyle を外して straight connector にする。直角経路が意図なら、始点と終点を同一 x か同一 y にそろえ、必要に応じて <Array as="points"> を routing hint として与える。points は controlHints であって経路を確定させないので、再 export して実経路を確認する |
| 縦横比がページ設定と合わない | png / jpg / svg の --size は既定が diagram で、内容の外接矩形へクロップする。このため pageWidth / pageHeight と出力サイズは一致しない。ページ全体で出したいなら --size page を使う。掲載幅に対する比率は書き出した .drawio.svg の width / height で測る |
| 書き出した SVG を汎用ラスタライザで見ると文字が消える / PDF 化したとき図中のテキストだけ出ない | PyMuPDF のような汎用 SVG レンダラは draw.io 由来の SVG のテキストを描画できないことがあり、図の欠陥と誤診しやすい。目視確認は同じ draw.io CLI で --format png --scale 1.5 を書き出して行い、最終判断は納品先の実レンダリング（web なら SVG、印刷なら PDF）で取る |
| CLI returns but PNG / SVG is missing or stale | Use absolute paths and Start-Process -Wait -PassThru; require exit code 0, output existence, and LastWriteTime newer than the source edit. If the .drawio is newer than its delivery assets, re-export before upload. Re-export to a temp path and compare hashes when timestamp evidence is ambiguous. Do one export per invocation and confirm the output timestamp before the next step; a chained ; or ForEach-Object loop otherwise reads the file the previous export has not finished writing. |