iOfficeAI/OfficeCLI · error · InvalidOperationException

mermaid failed to render: {ExtractMermaidMessage(dom)}

Error message

mermaid failed to render: {ExtractMermaidMessage(dom)}

What it means

The DOM title was MMDSYNTAX's sibling failure marker MMDSYNTAX->no: specifically the title was MMDERR, meaning mermaid.js loaded and parsed but threw during render (a runtime error, not a syntax error). ExtractMermaidMessage returns the captured exception text. This is a renderer-level failure, not bad input.

Source

Thrown at src/officecli/Core/Diagram/MermaidImageRenderer.cs:377

        var htmlPath = Path.Combine(Path.GetTempPath(), $"ocli_mmd_{Guid.NewGuid():N}.html");
        File.WriteAllText(htmlPath, html);
        try
        {
            var dom = HtmlScreenshot.DumpDom(htmlPath)
                ?? throw new InvalidOperationException("headless browser produced no output.");

            // The <title> is the AUTHORITATIVE outcome — not the presence of an <svg>.
            // On a syntax error mermaid.parse() rejects (we capture the message) but
            // STILL injects its red "Syntax error" bomb graphic into the DOM anyway
            // (suppressErrorRendering doesn't stop it). So a viewBox is present even on
            // failure; keying off the svg would screenshot the bomb and "succeed".
            // Trust the title: MMDREADY = real render, MMDSYNTAX = bad input, else infra.
            if (dom.Contains("<title>MMDSYNTAX</title>", StringComparison.Ordinal))
                throw new MermaidSyntaxException(
                    "mermaid syntax error: " + ExtractMermaidMessage(dom)
                    + "\n(fix the mermaid source, or use render=native for the built-in subset).");
            if (!dom.Contains("<title>MMDREADY</title>", StringComparison.Ordinal))
                throw new InvalidOperationException(
                    dom.Contains("<title>MMDERR</title>", StringComparison.Ordinal)
                    ? "mermaid failed to render: " + ExtractMermaidMessage(dom)
                    : "mermaid produced no diagram (mermaid.js failed to load or the render timed out).");

            var (w, h) = ParseSvgSize(dom);
            if (w <= 0 || h <= 0)
                throw new InvalidOperationException("mermaid rendered but produced no measurable svg viewBox.");

            var pngPath = Path.ChangeExtension(htmlPath, ".png");
            if (!HtmlScreenshot.CaptureChromeSized(htmlPath, pngPath,
                    (int)Math.Ceiling(w) + 2, (int)Math.Ceiling(h) + 2))
                throw new InvalidOperationException("headless screenshot failed.");
            return pngPath;
        }
        finally { try { File.Delete(htmlPath); } catch { /* best effort */ } }
    }

    /// <summary>Cache → one-time download → live CDN. Returns a URL usable as a

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Read the MMDERR message text for the render-time exception.
  2. If it names a layout plugin (elk), remove the layout frontmatter or ensure the ELK bundle loads (SourceNeedsElk path).
  3. Strip theme/frontmatter to isolate whether the styled-ESM path is the cause.
  4. Update or clear the cached mermaid.js so a different build is used, and retry.

Example fix

// before — frontmatter forces ELK which fails to load
---
layout: elk
---
flowchart TD
  A --> B

// after — default layout, renders without the plugin
flowchart TD
  A --> B
Defensive patterns

Strategy: try-catch

Validate before calling

// If the source opts into a layout/theme, confirm the plugin path will load
if (SourceNeedsElk(mermaid) && !ElkBundleAvailable())
    throw new InvalidOperationException("ELK layout requested but the ELK bundle is unavailable.");

Try / catch

try { png = MermaidImageRenderer.RenderViaChrome(mermaid, bg); }
catch (InvalidOperationException ex) when (ex.Message.Contains("mermaid failed to render", StringComparison.Ordinal))
{
    // retry without frontmatter, or fall back to native
    png = MermaidImageRenderer.RenderViaChrome(StripFrontmatter(mermaid), bg);
}

Prevention

When it happens

Trigger: mermaid.parse() succeeded but mermaid.render() threw — e.g. a layout plugin (elk) failed to load, a theme frontmatter referenced a missing layout, an internal mermaid bug for a particular construct, or a diagram type needing an ESM-only module that didn't load.

Common situations: Source declares a layout (e.g. 'layout: elk') but the ELK layouter bundle failed to load in BuildHtmlEsm; a mermaid version regression that throws on specific shapes; theme frontmatter pointing at an unavailable theme.

Related errors

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/2d43a030ff3d8b4b. Report an issue: GitHub.