iOfficeAI/OfficeCLI · error · ArgumentException

Column span {cellRef} covers {to - from + 1} columns (limit

Error message

Column span {cellRef} covers {to - from + 1} columns (limit 1024). Narrow the span or address columns individually as col[X].

What it means

A path axis ref like A:ZZZ expands to more than 1024 columns. The library refuses to materialize such a huge span because it would blow up memory and produce a workbook that is slow or impossible to open. The cap is a deliberate resource guard, not an Excel limit (Excel allows the full 16384-column grid).

Source

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

    /// aliases for the canonical col[X]/row[N] path segments — same policy as
    /// A1-style ranges (`A1:D10`), which the path grammar already accepts.
    /// Returns the expanded canonical segments in axis order (one per
    /// column/row in the span), or null when the segment is not an axis
    /// reference. Canonical readback paths remain col[X]/row[N].
    /// Spans wider than 1024 are rejected — a set over B:XFD (16k columns)
    /// is almost certainly a mistake, not intent.
    /// </summary>
    private static List<string>? TryExpandAxisRef(string cellRef)
    {
        var colRef = System.Text.RegularExpressions.Regex.Match(
            cellRef, @"^([A-Za-z]{1,3}):([A-Za-z]{1,3})$");
        if (colRef.Success)
        {
            var from = ColumnNameToIndex(colRef.Groups[1].Value.ToUpperInvariant());
            var to = ColumnNameToIndex(colRef.Groups[2].Value.ToUpperInvariant());
            if (from > to) (from, to) = (to, from);
            if (to - from + 1 > 1024)
                throw new ArgumentException(
                    $"Column span {cellRef} covers {to - from + 1} columns (limit 1024). Narrow the span or address columns individually as col[X].");
            var cols = new List<string>();
            for (var i = from; i <= to; i++) cols.Add($"col[{IndexToColumnName(i)}]");
            return cols;
        }
        var rowRef = System.Text.RegularExpressions.Regex.Match(cellRef, @"^(\d+):(\d+)$");
        if (rowRef.Success
            && uint.TryParse(rowRef.Groups[1].Value, out var r1) && r1 >= 1
            && uint.TryParse(rowRef.Groups[2].Value, out var r2) && r2 >= 1)
        {
            if (r1 > r2) (r1, r2) = (r2, r1);
            if (r2 - r1 + 1 > 1024)
                throw new ArgumentException(
                    $"Row span {cellRef} covers {r2 - r1 + 1} rows (limit 1024). Narrow the span or address rows individually as row[N].");
            var rows = new List<string>();
            for (var i = r1; i <= r2; i++) rows.Add($"row[{i}]");
            return rows;
        }

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Narrow the span to <= 1024 columns per call.
  2. Address columns individually as col[X] for scattered targets.
  3. Apply column defaults at the sheet or workbook level rather than expanding a span.

Example fix

// before
sheet.ApplyToAxis("A:XFD", ...);   // 16384 cols > 1024

// after
foreach (var colName in ChunkColumns("A", "XFD", 1024))
    sheet.ApplyToAxis($"{colName.Start}:{colName.End}", ...);
Defensive patterns

Strategy: validation

Validate before calling

const int MaxAxisSpan = 1024;
static bool ColumnSpanOk(string fromCol, string toCol) {
    int a = ColumnNameToIndex(fromCol), b = ColumnNameToIndex(toCol);
    return Math.Abs(b - a) + 1 <= MaxAxisSpan;
}

Try / catch

try { sheet.ApplyToAxis(span, ...); }
catch (ArgumentException ex) when (ex.Message.Contains("limit 1024")) {
    foreach (var chunk in ChunkSpan(span, 1024)) sheet.ApplyToAxis(chunk, ...);
}

Prevention

When it happens

Trigger: Passing an axis ref matching ^([A-Za-z]{1,3}):([A-Za-z]{1,3})$ where the span (to - from + 1) exceeds 1024, e.g. 'A:ZZZ' (702 cols ok, but 'A:XFD' = 16384 trips), 'B:XFD'.

Common situations: Trying to apply formatting or values across a whole-grid column range; autogenerated style rules that target broad spans; misunderstanding the per-call budget.

Related errors

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