iOfficeAI/OfficeCLI · error · ArgumentException

Invalid legend position '{posSpec}'. Valid: none, top, botto

Error message

Invalid legend position '{posSpec}'. Valid: none, top, bottom, left, right, topRight (or use 'none'/'false' to hide the legend).

What it means

The chart legend position setter (ChartExBuilder) normalizes the position spec via SchemaKeyNormalizer (dash/underscore equivalents), then maps it to a CX.SidePos enum value. Only top, bottom, left, right, and topRight are accepted (with short aliases t, b, l, r, tr). 'none' and 'false' hide the legend but are handled upstream, not in this switch. Any other value falls to the default arm and throws.

Source

Thrown at src/officecli/Core/Chart/ChartExBuilder.cs:466

        {
            Align = CX.PosAlign.Ctr,
            Overlay = false,
        };
        // CONSISTENCY(strict-enums / R34-1): unknown legend tokens used to
        // silently fall through to right; mirror cChart's strict validation.
        // Note: cx:legend's SidePos has no topRight — fall back to top with
        // a clear note rather than rejecting, since topRight is a valid
        // value for the regular cChart variant and users may pass it through.
        // CONSISTENCY(legend-separator-normalize): mirror SetterHelpers — dash
        // and underscore separators are equivalent (top-right == top_right).
        var posSpecNorm = SchemaKeyNormalizer.Normalize(posSpec);
        legend.Pos = posSpecNorm switch
        {
            "top" or "t" or "topright" or "tr" => CX.SidePos.T,
            "bottom" or "b" => CX.SidePos.B,
            "left" or "l"   => CX.SidePos.L,
            "right" or "r"  => CX.SidePos.R,
            _ => throw new ArgumentException(
                $"Invalid legend position '{posSpec}'. " +
                "Valid: none, top, bottom, left, right, topRight " +
                "(or use 'none'/'false' to hide the legend)."),
        };

        if (properties != null)
        {
            // Optional overlay flag — matches regular cChart's `legend.overlay`.
            var overlay = properties.GetValueOrDefault("legend.overlay")
                       ?? properties.GetValueOrDefault("legendoverlay");
            if (!string.IsNullOrEmpty(overlay))
                legend.Overlay = ParseHelpers.IsTruthy(overlay);

            // Compound font styling — "size:color:fontname", same form as
            // regular cChart's `legendfont`. Wraps an a:defRPr in cx:txPr.
            var legendFont = properties.GetValueOrDefault("legendfont")
                          ?? properties.GetValueOrDefault("legend.font");
            if (!string.IsNullOrEmpty(legendFont))

View on GitHub (pinned to 1ced45e900)

Solutions

Use one of the valid values: none, top, bottom, left, right, topRight (or aliases t, b, l, r, tr).
To hide the legend, pass 'none' or 'false' — these are handled before reaching the position switch.
For 'center', there is no cx:legend equivalent — restructure the chart or omit the legend position.

Example fix

// before
legend.Pos = "center";
// after
legend.Pos = "top"; // or "bottom", "left", "right", "topRight"

Defensive patterns

Strategy: validation

Validate before calling

static readonly HashSet<string> ValidLegendPositions = new(StringComparer.OrdinalIgnoreCase)
{ "top", "bottom", "left", "right", "topRight", "none", "false",
  "t", "b", "l", "r", "tr" };

static bool IsValidLegendPosition(string pos)
    => ValidLegendPositions.Contains(pos.Replace('-', '_').ToLowerInvariant());

Try / catch

try { chartExBuilder.SetLegendPosition(posSpec); }
catch (ArgumentException ex) when (ex.Message.StartsWith("Invalid legend position"))
{
    Console.Error.WriteLine($"{ex.Message}\nFalling back to default legend position.");
    chartExBuilder.SetLegendPosition("top");
}

Prevention

Use the canonical values: top, bottom, left, right, topRight.
Use 'none' or 'false' to hide the legend.
Validate against the allowed set before passing user input to the chart builder.

When it happens

Trigger: Setting legend position via the chart-ex builder's properties API with an unrecognized string, e.g. legendPos="middle", "center", "diagonal", or a locale-specific string. The value passes through SchemaKeyNormalizer.Normalize but does not match any switch arm.

Common situations: Typing 'center' or 'middle' (not supported by cx:legend SidePos). Using 'bottomRight' or 'topLeft' (only topRight exists for the regular cChart variant, but cx:legend has no topRight — it falls back to top). Passing an abbreviation not in the alias list.

Related errors

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