{"record":{"id":"4fdb9a9f1e183a49","repo":"iOfficeAI/OfficeCLI","slug":"column-break-index-cbidx-out-of-range-1-breaks","errorCode":null,"errorMessage":"Column break index {cbIdx} out of range (1-{breaks.Count})","messagePattern":"Column break index (.+?) out of range \\(1-(.+?)\\)","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Query.cs","lineNumber":488,"sourceCode":"            {\n                Path = path, Type = \"rowbreak\",\n                Format = { [\"row\"] = brk.Id?.Value ?? 0u, [\"manual\"] = brk.ManualPageBreak?.Value ?? false }\n            };\n            // Restricted-span page break (<brk min max>): surface a non-default\n            // column span so dump→replay reproduces it. Full-width default\n            // (min 0 / max 16383) is omitted to keep the readback clean.\n            if (brk.Min?.Value is { } rbMin && rbMin > 0) rbNode.Format[\"min\"] = (int)rbMin;\n            if (brk.Max?.Value is { } rbMax && rbMax != 16383u) rbNode.Format[\"max\"] = (int)rbMax;\n            return rbNode;\n        }\n        var cbMatch = Regex.Match(cellRef, @\"^colbreak\\[(\\d+)\\]$\", RegexOptions.IgnoreCase);\n        if (cbMatch.Success)\n        {\n            var cbIdx = int.Parse(cbMatch.Groups[1].Value);\n            var colBreaks = GetSheet(worksheet).GetFirstChild<ColumnBreaks>();\n            var breaks = colBreaks?.Elements<Break>().ToList() ?? new();\n            if (cbIdx < 1 || cbIdx > breaks.Count)\n                throw new ArgumentException($\"Column break index {cbIdx} out of range (1-{breaks.Count})\");\n            var brk = breaks[cbIdx - 1];\n            var cbNode = new DocumentNode\n            {\n                Path = path, Type = \"colbreak\",\n                Format = { [\"col\"] = (int)(brk.Id?.Value ?? 0u), [\"manual\"] = brk.ManualPageBreak?.Value ?? false }\n            };\n            // Restricted-span break: full-height default is min 0 / max 1048575.\n            if (brk.Min?.Value is { } cbMin && cbMin > 0) cbNode.Format[\"min\"] = (int)cbMin;\n            if (brk.Max?.Value is { } cbMax && cbMax != 1048575u) cbNode.Format[\"max\"] = (int)cbMax;\n            return cbNode;\n        }\n\n        // Validation path: /Sheet1/dataValidation[N] (canonical) or\n        // /Sheet1/validation[N] (legacy alias, R7-bt-6 CONSISTENCY)\n        var validationMatch = Regex.Match(cellRef, @\"^(?:dataValidation|validation)\\[(\\d+)\\]$\", RegexOptions.IgnoreCase);\n        if (validationMatch.Success)\n        {\n            var dvIdx = int.Parse(validationMatch.Groups[1].Value);","sourceCodeStart":470,"sourceCodeEnd":506,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Query.cs#L470-L506","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm the sheet actually has manual column breaks before indexing.","Use a 1-based index within [1, count].","Wrap Get in try/catch(ArgumentException) and read the valid range from the message."],"exampleFix":"// before\nvar cb = handler.Get(\"/Sheet1/colbreak[2]\"); // throws if <2 col breaks\n\n// after\nDocumentNode? GetColBreak(ExcelHandler h, string sheet, int n) {\n  try { return h.Get($\"/{sheet}/colbreak[{n}]\"); }\n  catch (ArgumentException) { return null; }\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"static int? ElementIndex(string cellRef, string element)\n{\n    var m = Regex.Match(cellRef, $@\"^{Regex.Escape(element)}\\[(\\d+)$\", RegexOptions.IgnoreCase);\n    return m.Success && int.TryParse(m.Groups[1].Value, out var i) ? i : null;\n}","tryCatchPattern":"try { return handler.Get($\"/{sheet}/colbreak[{n}]\"); }\ncatch (ArgumentException ex) { /* ex.Message carries the valid 1-N range */ return null; }","preventionTips":["All element indices are 1-based — there is no index 0.","Don't assume a sheet has manual column breaks; confirm before indexing.","Parse the valid range out of the exception message for a clear retry bound."],"tags":["excel","page-breaks","colbreak","path-index","argument-exception"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}