iOfficeAI/OfficeCLI · error · ArgumentException

unknown diagram theme '{theme}'. Valid: {string.Join(", ", T

Error message

unknown diagram theme '{theme}'. Valid: {string.Join(", ", Themes)}.

What it means

Thrown by MermaidImageRenderer.ComposeSource (MermaidImageRenderer.cs:132) when a non-null theme value is not in the accepted Themes set {default, dark, neutral, forest, base} (case-insensitive). ComposeSource bakes style options into a leading frontmatter block so they render and round-trip; unknown values are rejected before injection to avoid a malformed document. The set is kept in sync with schemas/help diagram documentation.

Source

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

    /// <summary>
    /// Bake the requested style options into the mermaid source as a leading
    /// <c>--- config: … ---</c> frontmatter block, so they render AND round-trip
    /// (the composed source is what gets stamped into alt-text). Returns the
    /// source unchanged when no option is set. Rejects unknown values with a
    /// message listing the valid ones. When the source already carries its own
    /// frontmatter or an <c>%%{init}%%</c> directive, the source wins and the
    /// options are ignored (caller may warn) — merging into an existing block is
    /// out of scope and would risk producing a malformed document.
    /// </summary>
    public static string ComposeSource(string mermaid, string? theme, string? layout, string? look)
    {
        theme = string.IsNullOrWhiteSpace(theme) ? null : theme.Trim();
        layout = string.IsNullOrWhiteSpace(layout) ? null : layout.Trim();
        look = string.IsNullOrWhiteSpace(look) ? null : look.Trim();
        if (theme == null && layout == null && look == null) return mermaid;

        if (theme != null && !Themes.Contains(theme))
            throw new ArgumentException($"unknown diagram theme '{theme}'. Valid: {string.Join(", ", Themes)}.");
        if (layout != null && !Layouts.Contains(layout))
            throw new ArgumentException($"unknown diagram layout '{layout}'. Valid: {string.Join(", ", Layouts)}.");
        if (look != null && !Looks.Contains(look))
            throw new ArgumentException($"unknown diagram look '{look}'. Valid: classic, handDrawn.");

        var lead = mermaid.TrimStart();
        if (lead.StartsWith("---", StringComparison.Ordinal) || lead.StartsWith("%%{", StringComparison.Ordinal))
            return mermaid; // source already declares config — do not double-inject

        var sb = new StringBuilder("---\nconfig:\n");
        if (theme != null) sb.Append("  theme: ").Append(theme.ToLowerInvariant()).Append('\n');
        if (layout != null) sb.Append("  layout: ").Append(layout.ToLowerInvariant()).Append('\n');
        // look's canonical mermaid spelling is camelCase handDrawn; normalize.
        if (look != null)
            sb.Append("  look: ")
              .Append(look.Equals("handdrawn", StringComparison.OrdinalIgnoreCase) ? "handDrawn" : "classic")
              .Append('\n');
        sb.Append("---\n").Append(mermaid);

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Use one of: default, dark, neutral, forest, base.
  2. Leave the theme unset (null/empty) to use mermaid's built-in default.

Example fix

// before
theme=light
// after
theme=default
Defensive patterns

Strategy: validation

Validate before calling

static readonly HashSet<string> ValidThemes = new(StringComparer.OrdinalIgnoreCase) { "default","dark","neutral","forest","base" };
static string ValidateTheme(string theme) => ValidThemes.Contains(theme ?? "") ? theme : throw new ArgumentException($"unknown theme '{theme}'");

Type guard

static bool IsValidTheme(string theme) => ValidThemes.Contains(theme ?? "");

Try / catch

try { MermaidImageRenderer.ComposeSource(mermaid, theme, null, null); }
catch (ArgumentException ex) when (ex.Message.Contains("unknown diagram theme"))
{ /* default to null theme or pick from {default,dark,neutral,forest,base} */ }

Prevention

When it happens

Trigger: Setting a diagram theme to 'light' (use 'default'), 'black', 'monochrome', 'ocean', or any value outside {default, dark, neutral, forest, base}.

Common situations: Guessing 'light' instead of 'default'; using a mermaid version-specific theme name not in this set; passing a hex color or custom theme object that this option does not accept.

Related errors

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