Mermaid diagrams render with invisible/missing text labels on Linux

[Dnreikronos]

Pre-submit Checks

• I have searched Warp bugs and there are no duplicates
• I have searched Warp known issues page and my issue is not there
• I have an issue with AI and have included the debugging ID (Optional, but helps expedite the AI quality fix). Debugging ID instructions
• I have technical issue and have included the logs (optional, but helps expedite the bug fix). Log instructions

Describe the bug

Mermaid diagrams render structurally (boxes, arrows, lines, connectors all visible) but all text is completely invisible. Node labels, edge labels, sequence diagram participant names — every text element is blank. The diagrams are correct in layout but entirely unreadable.

Affected diagram types:

• Flowcharts / graph diagrams
• Sequence diagrams

Root cause (confirmed): The SVG renderer fails to resolve generic CSS font families (sans-serif, monospace, etc.) used by mermaid when the expected system fonts are not installed. Since mermaid defaults to these generic families for all text elements, every label disappears silently.

I fixed this exact same bug in Zed Editor — see zed-industries/zed#51623. The fix involved bundling fallback fonts and properly resolving generic font family names in the SVG renderer. The same approach would apply here.

To reproduce

1. Open Warp on Linux
2. Use AI chat (or any surface that renders mermaid) to generate a mermaid diagram
3. Observe that diagram shapes and arrows appear correctly, but all text is invisible

Expected behavior

Text labels should render inside nodes, on arrows, and as participant names — matching how mermaid diagrams display on macOS.

Screenshots, videos, and logs

Operating system (OS)

Linux

Operating system and version

CachyOS (Arch-based), kernel 7.0.1-1-cachyos

Shell Version

zsh 5.9

Current Warp version

Latest stabley

Regression

No, this bug or issue has existed throughout my experience using Warp

Recent working Warp date

N/A

Additional context

Using Wayland/X11 ().

Prior art — fix for same bug in Zed Editor:

• Issue: zed-industries/zed#51466
• Fix (merged): zed-industries/zed#51623 — bundled fallback fonts + fixed generic font family resolution in SVG renderer

The root cause is the same: mermaid emits SVG text elements with generic font families (sans-serif), and the renderer has no fallback when those fonts aren't available on the system. Bundling a default sans-serif font (e.g., Inter, Noto Sans) and mapping generic family names to it resolves the issue.

Does this block you from using Warp daily?

No

Is this an issue only in Warp?

Yes, I confirmed that this only happens in Warp, not other terminals.

Warp Internal (ignore): linear-label:b9d78064-c89e-4973-b153-5178a31ee54e

None

[oz-for-oss]

@Manoj7ar

Here's what I found while triaging this issue:

The added version and fc-match output are enough to continue without more reporter info. Since sans-serif resolves to Noto Sans on the affected system, this looks more like Warp's SVG font-family fallback path than simply missing Linux fonts.

Maintainer details

I concluded that mermaid diagrams on Linux render SVG geometry but lose all text labels, likely due to Warp's SVG/usvg font-family fallback path for generic CSS families..

Triage summary

This remains an actionable Linux-specific Mermaid/SVG text rendering bug. The reporter's follow-up supplies the exact affected build (v0.2026.04.27.15.32.stable_02) and shows fc-match sans-serif resolves to Noto Sans, so the issue no longer needs reporter info for initial triage.

Evidence

• The report includes reproduction steps, a screenshot, Linux environment details, exact Warp version, and fc-match sans-serif output.
• The affected surface is Mermaid-rendered SVG text: shapes, arrows, and layout render, while labels disappear.
• crates/editor/src/content/mermaid_diagram.rs converts Mermaid source to SVG bytes with mermaid_to_svg::render_mermaid_to_svg.
• crates/editor/src/render/element/mermaid.rs renders the generated asset through WarpUI's Image element.
• crates/warpui_core/src/image_cache.rs detects SVG bytes and calls usvg::Tree::from_data with a shared usvg::fontdb::Database initialized by load_system_fonts().
• I did not find explicit generic CSS family mapping or bundled fallback loading for SVG text in this path. Bundled app fonts exist under app/assets/bundled/fonts, but this SVG font database path does not appear to load them.
• crates/warpui_core/src/image_cache_tests.rs has an SVG text rasterization test for an explicit installed font family, but not for generic families such as sans-serif.

Likely root cause

The reporter's original missing-font framing should be narrowed: their system fontconfig does resolve sans-serif to Noto Sans, so the problem is likely not simply absent system fonts. The current code still supports the broader diagnosis that Warp's SVG rendering path relies on usvg/fontdb system-font discovery without a deterministic default font and without explicit mapping from Mermaid's generic CSS families (sans-serif, serif, monospace) to known available faces. That can allow SVG geometry to render while text layout/rasterization silently produces no visible labels on some Linux/fontconfig setups.

Confidence is medium because the exact CachyOS environment was not reproduced locally, but the code path and reporter follow-up are consistent with the symptom.

Duplicate check

I compared this against the recent/open candidates. #9372 and its referenced #8819 are related Linux font-rendering issues, but they focus on terminal/emoji glyph rendering and Failed to get raster image style failures rather than Mermaid-generated SVG labels. I would not mark #9402 as a duplicate based on the current evidence.

Suggested routing

• @vorporeal for the shared WarpUI/SVG image rendering path.
• @kevinyang372 or @bnavetta for the editor/notebook Mermaid markdown rendering path.

Suggested next step

Investigate adding a deterministic SVG text fallback path: load a bundled sans/mono fallback into the usvg font database, map CSS generic families emitted by Mermaid to known faces, set a deterministic default usvg::Options.font_family, and add a regression test that rasterizes SVG text using font-family="sans-serif" and asserts visible non-transparent text pixels.

This is my automated analysis and may be incorrect. A maintainer will verify the details.

Powered by Oz

[Dnreikronos]

@Dnreikronos

Here's what I found while triaging this issue:

This looks actionable as a Linux-specific Mermaid/SVG text rendering bug. The current evidence supports the missing generic-font fallback theory, and the failure appears distinct from broader terminal/emoji font-rendering reports.

I have a few follow-up questions before I can narrow this down:

1. Can you paste the exact Warp version/build from Settings > Account?
2. Can you share the output of fc-match sans-serif from the affected system?

Reply in-thread with those details and the triage workflow will automatically re-evaluate the issue and update the diagnosis, labels, and next steps.

Maintainer details
I concluded that linux Mermaid diagrams appear to render SVG geometry but drop all SVG text labels, likely because Warp's SVG rendering path relies on system font resolution without a bundled/generic-family fallback..

Triage summary

This appears to be an actionable Linux-specific rendering bug in the Mermaid markdown/SVG path. The reporter observes that Mermaid diagram shapes, arrows, and layout render, but SVG text labels are invisible across flowcharts and sequence diagrams.

Evidence

• The report includes clear reproduction steps, Linux environment details, and screenshot evidence.
• The affected content is Mermaid-rendered SVG rather than ordinary terminal glyph rendering.
• crates/editor/src/content/mermaid_diagram.rs converts Mermaid source into SVG bytes via mermaid_to_svg.
• crates/editor/src/render/element/mermaid.rs displays the resulting asset as an image block.
• crates/warpui_core/src/image_cache.rs parses SVGs using a static usvg::fontdb::Database initialized with load_system_fonts().
• I did not find a bundled SVG fallback font or explicit mapping from CSS generic font families such as sans-serif/monospace into a known bundled family in this path.

Likely root cause

The reporter's proposed root cause is plausible and consistent with the current code: Mermaid emits SVG text using generic font families, and Warp's SVG parsing/rasterization path appears to rely on the host system font database. On Linux systems where fontconfig/usvg cannot resolve those generic families to an installed font with usable glyphs, text can disappear while SVG geometry still renders.

Confidence is medium because I did not reproduce on the reporter's exact CachyOS/fontconfig setup, and the exact Warp build is not included.

Duplicate check

I compared this against the recent/open issues list. #9372 and its referenced #8819 are related Linux font-rendering reports, but they focus on broader terminal/emoji glyph rendering rather than Mermaid-generated SVG text. I would not mark #9402 as a duplicate based on the available evidence.

Suggested routing

• @vorporeal for the shared WarpUI/SVG image rendering path.
• @kevinyang372 or @bnavetta for the editor/Mermaid markdown rendering path.

Suggested next step

Investigate adding a deterministic fallback for SVG text rendering on Linux, such as loading a bundled sans-serif font into the SVG font database and/or mapping CSS generic font families emitted by Mermaid to known available fallback families.

Question reasoning

1. Can you paste the exact Warp version/build from Settings > Account? — The report says latest stable, but the exact build is needed to confirm the affected version range and validate any future fix.
2. Can you share the output of fc-match sans-serif from the affected system? — The suspected failure depends on how the reporter's Linux fontconfig setup resolves generic SVG font families, which cannot be derived from the issue body.

This is my automated analysis and may be incorrect. A maintainer will verify the details.

Powered by Oz

Can you paste the exact Warp version/build from Settings > Account?:
v0.2026.04.27.15.32.stable_02

Can you share the output of fc-match sans-serif from the affected system?:
NotoSans-Regular.ttf: "Noto Sans" "Regular"

[Dnreikronos]

/oz-reanalyze

[Dnreikronos]

I would like to work on this, if it's possible.

[Manoj7ar]

@oz-agent proceed working

[Manoj7ar]

@oz-agent I dug into the rendering path and the likely root cause is in Warp’s SVG font resolution on Linux.

Current path looks like:

• crates/editor/src/content/mermaid_diagram.rs → Mermaid source → SVG bytes
• crates/editor/src/render/element/mermaid.rs → renders SVG asset
• crates/warpui_core/src/image_cache.rs → parses SVG with usvg::Tree::from_data(...)
• static font DB initialized with usvg::fontdb::Database::new() + load_system_fonts()

Problem:
Mermaid emits generic CSS font families (sans-serif, monospace, etc). Warp appears to rely only on system font discovery through fontdb, but there’s no deterministic fallback or explicit generic-family mapping in the SVG path.

Important detail:
fc-match sans-serif resolves correctly (Noto Sans), so this is likely not “missing fonts” — it’s likely usvg/fontdb generic-family fallback handling inside Warp’s SVG pipeline.

Suggested implementation:

1. In crates/warpui_core/src/image_cache.rs

   • load bundled fallback fonts into the SVG font DB (e.g. Inter / Noto Sans / JetBrains Mono)

2. Add explicit generic-family mapping:

   • sans-serif → bundled sans font
   • serif → bundled serif font
   • monospace → bundled mono font

3. Set a deterministic default usvg::Options.font_family

4. Add regression test:

   • rasterize SVG containing <text font-family="sans-serif">hello</text>
   • assert non-transparent pixels exist

This is essentially the same class of fix as the merged Zed fix:
zed-industries/zed#51623