iOfficeAI/OfficeCLI · error · ArgumentException

Column break index {cbIdx} out of range (1-{breaks.Count})

Error message

Column break index {cbIdx} out of range (1-{breaks.Count})

What it means

Thrown for /SheetName/colbreak[N] when N is outside the 1-based range [1, <colBreaks.Count>]. Column breaks (manual vertical page breaks) live in the worksheet's <colBreaks> element (full-height default max 1048575). With no column breaks, any index — including colbreak[0] — is rejected.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Query.cs:488

            {
                Path = path, Type = "rowbreak",
                Format = { ["row"] = brk.Id?.Value ?? 0u, ["manual"] = brk.ManualPageBreak?.Value ?? false }
            };
            // Restricted-span page break (<brk min max>): surface a non-default
            // column span so dump→replay reproduces it. Full-width default
            // (min 0 / max 16383) is omitted to keep the readback clean.
            if (brk.Min?.Value is { } rbMin && rbMin > 0) rbNode.Format["min"] = (int)rbMin;
            if (brk.Max?.Value is { } rbMax && rbMax != 16383u) rbNode.Format["max"] = (int)rbMax;
            return rbNode;
        }
        var cbMatch = Regex.Match(cellRef, @"^colbreak\[(\d+)\]$", RegexOptions.IgnoreCase);
        if (cbMatch.Success)
        {
            var cbIdx = int.Parse(cbMatch.Groups[1].Value);
            var colBreaks = GetSheet(worksheet).GetFirstChild<ColumnBreaks>();
            var breaks = colBreaks?.Elements<Break>().ToList() ?? new();
            if (cbIdx < 1 || cbIdx > breaks.Count)
                throw new ArgumentException($"Column break index {cbIdx} out of range (1-{breaks.Count})");
            var brk = breaks[cbIdx - 1];
            var cbNode = new DocumentNode
            {
                Path = path, Type = "colbreak",
                Format = { ["col"] = (int)(brk.Id?.Value ?? 0u), ["manual"] = brk.ManualPageBreak?.Value ?? false }
            };
            // Restricted-span break: full-height default is min 0 / max 1048575.
            if (brk.Min?.Value is { } cbMin && cbMin > 0) cbNode.Format["min"] = (int)cbMin;
            if (brk.Max?.Value is { } cbMax && cbMax != 1048575u) cbNode.Format["max"] = (int)cbMax;
            return cbNode;
        }

        // Validation path: /Sheet1/dataValidation[N] (canonical) or
        // /Sheet1/validation[N] (legacy alias, R7-bt-6 CONSISTENCY)
        var validationMatch = Regex.Match(cellRef, @"^(?:dataValidation|validation)\[(\d+)\]$", RegexOptions.IgnoreCase);
        if (validationMatch.Success)
        {
            var dvIdx = int.Parse(validationMatch.Groups[1].Value);

View on GitHub (pinned to 1ced45e900)

Solutions

1. Confirm the sheet actually has manual column breaks before indexing.
2. Use a 1-based index within [1, count].
3. Wrap Get in try/catch(ArgumentException) and read the valid range from the message.

Example fix

// before
var cb = handler.Get("/Sheet1/colbreak[2]"); // throws if <2 col breaks

// after
DocumentNode? GetColBreak(ExcelHandler h, string sheet, int n) {
  try { return h.Get($"/{sheet}/colbreak[{n}]"); }
  catch (ArgumentException) { return null; }
}

static int? ElementIndex(string cellRef, string element)
{
    var m = Regex.Match(cellRef, $@"^{Regex.Escape(element)}\[(\d+)$", RegexOptions.IgnoreCase);
    return m.Success && int.TryParse(m.Groups[1].Value, out var i) ? i : null;
}

try { return handler.Get($"/{sheet}/colbreak[{n}]"); }
catch (ArgumentException ex) { /* ex.Message carries the valid 1-N range */ return null; }

When it happens

Trigger: handler.Get("/Sheet1/colbreak[2]") on a sheet with fewer than 2 manual column page breaks, or colbreak[1] on a sheet with none. Using a 0-based index.

Common situations: Assuming a sheet has vertical page breaks. Off-by-one from zero-based indexing. Hard-coded break indices after the file was edited and breaks removed.

Related errors

• Row break index {rbIdx} out of range (1-{breaks.Count})
• Chart index {caChartIdx} out of range (1-{caAllCharts.Count}
• Chart index {chartIdx} out of range (1-{allCharts.Count})
• Series {seriesIdx} not found (total: {seriesChildren.Count})
• PivotTable index {ptIdx} out of range (1-{pivotParts.Count})

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