iOfficeAI/OfficeCLI · error · ArgumentException

Invalid sparkline range '{range}': row '{tm.Groups[2].Value}

Error message

Invalid sparkline range '{range}': row '{tm.Groups[2].Value}' is outside Excel's grid (1..1048576).

What it means

The sparkline range passed the shape check but a row number is outside Excel's grid (must be 1..1048576). As with the column case, Excel tolerates the bad ref but the sparkline is silently broken, so the library rejects up-front.

Source

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

                $"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
        // patterns that pass schema validation but make real Excel refuse
        // the file: doubled/trailing '!' ("乱码!!!") and stray '#' outside
        // the known error literals ("乱码###").
        // Formula-length ceiling (8192) applies to defined-name bodies too.
        ValidateFormulaLength(refText, "defined-name ref");

View on GitHub (pinned to 1ced45e900)

Solutions

Clamp the row to [1,1048576] before building the range string.
Validate row tokens are positive and within bounds upstream.
Use 1-based row numbering consistently.

Example fix

// before
sheet.SetSparkline("F1", data: "A0:E0");

// after
sheet.SetSparkline("F1", data: "A1:E1");

Defensive patterns

Strategy: validation

Validate before calling

static bool RowWithinGrid(long row) => row >= 1 && row <= 1048576;

Try / catch

try { sheet.SetSparkline(loc, data); }
catch (ArgumentException ex) when (ex.Message.Contains("1..1048576")) {
    // clamp row and retry
}

Prevention

Use 1-based row numbering everywhere; clamp to [1,1048576].
Validate row tokens before assembling the range string.

When it happens

Trigger: Passing a sparkline range with a row token like '0', '1048577', or '99999999'. The long.TryParse + bounds check fails.

Common situations: Off-by-one row indexing (zero-based leaked into a one-based ref); generated indices never clamped; a row counter that overflowed.

Related errors

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