iOfficeAI/OfficeCLI · error · ArgumentException

Invalid sparkline range '{range}': column '{tm.Groups[1].Val

Error message

Invalid sparkline range '{range}': column '{tm.Groups[1].Value}' is outside Excel's grid (A..XFD).

What it means

The sparkline range passed the shape check but a column letter resolves to an index outside Excel's grid (must be 1..16384, i.e. A..XFD). Excel tolerates rather than rejects such refs in <xne:f>, but the sparkline is silently broken, so the library tightens to the same severity other cell-ref entry points enforce.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Helpers.Validation.cs:608

        r = r.Replace("$", "");
        var ok = r.Length > 0 && r.Split(':').All(tok =>
            System.Text.RegularExpressions.Regex.IsMatch(tok.Trim(), @"^([A-Za-z]{1,3}\d+|[A-Za-z]{1,3}|\d+)$"));
        if (!ok)
            throw new ArgumentException(
                $"Invalid sparkline range '{range}'. Expected an A1 range like A1:E1 (optionally sheet-qualified).");
        // Grid-bounds check, same family as ValidateSqref: shape-valid B0 or
        // A99999999 landed verbatim in <xne:f>. Excel tolerates rather than
        // rejects these, but the sparkline is silently broken — tighten to
        // the severity every other cell-ref entry point now enforces.
        foreach (var tok in r.Split(':'))
        {
            var tm = System.Text.RegularExpressions.Regex.Match(tok.Trim(),
                @"^([A-Za-z]{1,3})?(\d+)?$");
            if (tm.Groups[1].Success && tm.Groups[1].Value.Length > 0)
            {
                var colIdx = ColumnNameToIndex(tm.Groups[1].Value.ToUpperInvariant());
                if (colIdx < 1 || colIdx > 16384)
                    throw new ArgumentException(
                        $"Invalid sparkline range '{range}': column '{tm.Groups[1].Value}' is outside Excel's grid (A..XFD).");
            }
            if (tm.Groups[2].Success && tm.Groups[2].Value.Length > 0
                && (!long.TryParse(tm.Groups[2].Value, out var rowN) || rowN < 1 || rowN > 1048576))
                throw new ArgumentException(
                    $"Invalid sparkline range '{range}': row '{tm.Groups[2].Value}' is outside Excel's grid (1..1048576).");
        }
    }

    /// <summary>Sanity-check a defined-name body. Full formula validation is
    /// out of scope, but a sheet-qualified reference must name an existing
    /// sheet and carry a plausible range/name after the '!' — garbage like
    /// "乱码!!!" written verbatim makes real Excel refuse the file.</summary>
    internal void ValidateDefinedNameRef(string refText)
    {
        // Defined-name bodies are full formulas — validating them properly
        // is out of scope (functions, unions, cross-part brackets, escaped
        // apostrophes are all legal). Reject only the empirically fatal

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Cap the column index to [1,16384] before building the range string.
  2. Use IndexToColumnName to construct valid column letters.
  3. Switch from per-column sparkline data to a row-bounded range if you only need a slice.

Example fix

// before
sheet.SetSparkline("F1", data: "XFE1:ZZZ1");

// after
sheet.SetSparkline("F1", data: "A1:XFD1");
Defensive patterns

Strategy: validation

Validate before calling

static bool ColumnWithinGrid(string colLetters) {
    int idx = 0;
    foreach (var ch in colLetters.ToUpperInvariant()) idx = idx * 26 + (ch - 'A' + 1);
    return idx >= 1 && idx <= 16384;
}

Try / catch

try { sheet.SetSparkline(loc, data); }
catch (ArgumentException ex) when (ex.Message.Contains("outside Excel's grid")) {
    // clamp column to XFD and retry
}

Prevention

When it happens

Trigger: Passing a sparkline range with a column like 'ZZZ' (18278), 'XFE' (16385), or any 3-letter combo past XFD. ColumnNameToIndex returns > 16384 (or < 1).

Common situations: Generated column refs from an unbounded counter; copy-paste from a tool with a wider grid; arithmetic that overflowed into a 4th column letter.

Related errors

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