iOfficeAI/OfficeCLI · warning · MermaidSyntaxException

mermaid syntax error: {msg} (fix the mermaid source, or use

Error message

mermaid syntax error: {msg} (fix the mermaid source, or use render=native for the built-in subset).

What it means

mmdc exited non-zero (or produced no output file) and the combined stderr+stdout matched a known syntax-error signature via LooksLikeSyntaxError (phrases: 'Parse error', 'Lexical error', 'No diagram type detected', 'UnknownDiagramError', 'Expecting '). The renderer reclassifies this as MermaidSyntaxException so the Add path surfaces it as bad input instead of treating it as a broken mmdc and falling back.

Source

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

            using var p = Process.Start(psi)
                ?? throw new InvalidOperationException("failed to start mmdc.");
            // Async-drain both streams: the serial stderr-then-stdout reads
            // interlocked when mmdc filled the stdout pipe first (bounded by
            // the 120s kill below, but a wasted two minutes per diagram).
            var errTask = p.StandardError.ReadToEndAsync();
            var outTask = p.StandardOutput.ReadToEndAsync();
            if (!p.WaitForExit(120_000))
            {
                try { p.Kill(true); } catch { /* best effort */ }
                throw new InvalidOperationException("mmdc timed out after 120s.");
            }
            if (p.ExitCode != 0 || !File.Exists(outPath))
            {
                var msg = $"{errTask.Result}{outTask.Result}".Trim();
                // A parse/unknown-type failure is bad input, not a broken mmdc; class
                // it as syntax so the Add path surfaces it (and does not fall back).
                if (LooksLikeSyntaxError(msg))
                    throw new MermaidSyntaxException(
                        $"mermaid syntax error: {msg} "
                        + "(fix the mermaid source, or use render=native for the built-in subset).");
                throw new InvalidOperationException($"mmdc failed (exit {p.ExitCode}). {msg}".Trim());
            }
            return outPath;
        }
        finally { try { File.Delete(inPath); } catch { /* best effort */ } }
    }

    // ----- chrome-family browser (mermaid.js in a page → sized screenshot) --------------

    /// <summary>Two chrome passes: dump the DOM to read the diagram's viewBox, then
    /// screenshot at exactly that size (HiDPI). PNG bakes in the browser's rendering
    /// so mermaid's foreignObject labels — invisible to Office as SVG — appear.</summary>
    private static string RenderViaChrome(string mermaid, string? background)
    {
        // A styled source (theme/layout/look frontmatter) is rendered by the ESM
        // build (the UMD global does not render frontmatter, and elk is ESM-only);

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Read the {msg} portion: it is mermaid's own parse error with line/column — fix the cited syntax.
  2. If the syntax is valid for a newer mermaid, upgrade @mermaid-js/mermaid-cli (`npm i -g @mermaid-js/mermaid-cli@latest`) and point OFFICECLI_MMDC at it.
  3. If the diagram type isn't supported, switch to render=native for the built-in subset, or simplify the source to a supported type.
  4. Validate the source with `mmdc -i src.mmd -o /tmp/x.png` directly to confirm the parse error reproduces outside this tool.

Example fix

// before — mermaid with a typo / unsupported type
graph TD
  A -->B   C

// after — valid flowchart syntax
graph TD
  A --> B
  B --> C
Defensive patterns

Strategy: validation

Validate before calling

// Validate mermaid source against the same parse-failure signatures before rendering
static bool LooksLikeValidMermaid(string src)
{
    if (string.IsNullOrWhiteSpace(src)) return false;
    // Cheap pre-check: must reference a known diagram type keyword
    var head = src.TrimStart('-', ' ', '\n', '\r');
    return head.Contains("graph", StringComparison.OrdinalIgnoreCase)
        || head.Contains("flowchart", StringComparison.OrdinalIgnoreCase)
        || head.Contains("sequenceDiagram", StringComparison.OrdinalIgnoreCase)
        || head.Contains("pie", StringComparison.OrdinalIgnoreCase);
}

Try / catch

try { png = MermaidImageRenderer.Render(mermaid, bg); }
catch (MermaidSyntaxException ex)
{
    // bad input — surface to the user, do NOT fall back to a different renderer
    result.AddError("mermaid", ex.Message);
}

Prevention

When it happens

Trigger: Calling the mmdc render path with mermaid source that fails to parse: an unknown diagram type, a malformed directive, a typo in a keyword, or a graph/flowchart with an unmatched bracket. mmdc returns non-zero, no PNG is written, and its stderr contains one of the recognized parse-failure phrases.

Common situations: User pastes a mermaid snippet using a diagram type or directive not supported by the installed @mermaid-js/mermaid-cli version; copy-paste introduces a stray character; the source uses newer mermaid syntax than the bundled mmdc supports.

Related errors

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