iOfficeAI/OfficeCLI · error · System.ArgumentException

Invalid 'col' value: '{cbColStr}'. Column breaks must be bet

Error message

Invalid 'col' value: '{cbColStr}'. Column breaks must be between 1 and 16384 (A-XFD).

What it means

Thrown by AddColBreak when the resolved column index is less than 1 or greater than 16384 (column XFD, the last column in an OOXML grid). cbColIdx accepts either a numeric string (uint.TryParse) or a column letter (via ColumnNameToIndex), then range-checks. Out-of-grid ids produce invalid OOXML that Excel rejects at validate/open time.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Add.Cells.cs:1383

    {
        var index = position?.Index;
        var cbSegments = parentPath.TrimStart('/').Split('/', 2);
        var cbSheetName = cbSegments[0];
        var cbWorksheet = FindWorksheet(cbSheetName)
            ?? throw new ArgumentException($"Sheet not found: {cbSheetName}");
        var cbWs = GetSheet(cbWorksheet);

        var cbColStr = properties.GetValueOrDefault("col") ?? properties.GetValueOrDefault("column")
            ?? properties.GetValueOrDefault("index")
            ?? throw new ArgumentException("'col' property is required for colbreak");
        // Accept both numeric index (e.g. "3") and column letter (e.g. "C")
        var cbColIdx = uint.TryParse(cbColStr, out var cbNumVal)
            ? cbNumVal
            : (uint)ColumnNameToIndex(cbColStr.ToUpperInvariant());
        // Same schema Min/Max guard as rowbreak: 0 / beyond-XFD ids write
        // invalid OOXML that only surfaces at validate/open time.
        if (cbColIdx < 1 || cbColIdx > 16384)
            throw new ArgumentException(
                $"Invalid 'col' value: '{cbColStr}'. Column breaks must be between 1 and 16384 (A-XFD).");

        var colBreaks = cbWs.GetFirstChild<ColumnBreaks>();
        if (colBreaks == null)
        {
            colBreaks = new ColumnBreaks();
            cbWs.AppendChild(colBreaks);
        }
        // Optional restricted row span (min/max) — mirrors the Set path.
        var cbBreak = new Break { Id = cbColIdx, Max = 1048575u, ManualPageBreak = true };
        if (properties.TryGetValue("min", out var cbMinS) && uint.TryParse(cbMinS, out var cbMin))
            cbBreak.Min = cbMin;
        if (properties.TryGetValue("max", out var cbMaxS) && uint.TryParse(cbMaxS, out var cbMax))
            cbBreak.Max = cbMax;
        if (properties.TryGetValue("manual", out var cbMan))
            cbBreak.ManualPageBreak = IsTruthy(cbMan);
        colBreaks.AppendChild(cbBreak);
        colBreaks.Count = (uint)colBreaks.Elements<Break>().Count();

View on GitHub (pinned to 1ced45e900)

Solutions

Use a column in the range 1-16384 (numeric) or A-XFD (letter).
If the value came from a 0-based source, add 1 before passing it.
Clamp computed indices and warn if the clamp changes the value.

Example fix

// before
props["col"] = "0"; // 0-based

// after
props["col"] = "1"; // or "A" — OOXML columns are 1-based

Defensive patterns

Strategy: validation

Validate before calling

string colStr = props.GetValueOrDefault("col") ?? props.GetValueOrDefault("column") ?? props.GetValueOrDefault("index") ?? "";
uint col = uint.TryParse(colStr, out var n) ? n : (uint)ColumnNameToIndex(colStr.ToUpperInvariant());
if (col < 1 || col > 16384)
    throw new ArgumentOutOfRangeException("col", "must be 1-16384 (A-XFD)");
handler.Add("/Sheet1", "colbreak", null, props);

Type guard

static bool IsValidColumn(uint col) => col >= 1 && col <= 16384;

Prevention

Treat column indices as 1-based (A=1).
Clamp computed column numbers to 1-16384 and warn on clamping.
Prefer letter form (A-XFD) for readability and validate the letter range.

When it happens

Trigger: properties["col"]="0", properties["col"]="16385", or a letter beyond XFD (e.g. "XFE"). Note: an empty or non-letter/non-numeric col value fails uint.TryParse and then ColumnNameToIndex, which throws its own error before reaching this guard. This guard fires for values that parse but are out of grid range.

Common situations: 0-based column indexing assumption. A letter string like "AA" that overflows when computed for a very wide sheet. Script-derived column index that exceeds XFD.

Related errors

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