{"record":{"id":"a89e3b401efab605","repo":"iOfficeAI/OfficeCLI","slug":"run-index-runidx-out-of-range-1-runs-count","errorCode":null,"errorMessage":"Run index {runIdx} out of range (1-{runs.Count})","messagePattern":"Run index (.+?) out of range \\(1-(.+?)\\)","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Query.cs","lineNumber":936,"sourceCode":"        // Handle /SheetName/A1/run[N] (rich text run direct access)\n        var runGetMatch = Regex.Match(cellRef, @\"^([A-Z]+\\d+)/run\\[(\\d+)\\]$\", RegexOptions.IgnoreCase);\n        if (runGetMatch.Success)\n        {\n            var runCellRef = runGetMatch.Groups[1].Value.ToUpperInvariant();\n            var runIdx = int.Parse(runGetMatch.Groups[2].Value);\n            ParseCellReference(runCellRef);\n            var runCell = FindCell(data, runCellRef);\n            if (runCell == null)\n                throw new ArgumentException($\"Cell {runCellRef} not found\");\n            if (runCell.DataType?.Value != CellValues.SharedString ||\n                !int.TryParse(runCell.CellValue?.Text, out var sstIdx))\n                throw new ArgumentException($\"Cell {runCellRef} is not a rich text cell\");\n            var sstPart = _doc.WorkbookPart?.GetPartsOfType<SharedStringTablePart>().FirstOrDefault();\n            var ssi = sstPart?.SharedStringTable?.Elements<SharedStringItem>().ElementAtOrDefault(sstIdx);\n            if (ssi == null) throw new ArgumentException($\"SharedString entry {sstIdx} not found\");\n            var runs = ssi.Elements<Run>().ToList();\n            if (runIdx < 1 || runIdx > runs.Count)\n                throw new ArgumentException($\"Run index {runIdx} out of range (1-{runs.Count})\");\n            return RunToNode(runs[PathIndex.ToArrayIndex(runIdx)], $\"/{sheetNameFromPath}/{runCellRef}/run[{runIdx}]\");\n        }\n\n        if (cellRef.Contains(':'))\n        {\n            // Range — validate both endpoints\n            var rangeParts = cellRef.Split(':');\n            ParseCellReference(rangeParts[0]);\n            if (rangeParts.Length > 1) ParseCellReference(rangeParts[1]);\n            return GetCellRange(sheetNameFromPath, data, cellRef, depth, worksheet);\n        }\n        else\n        {\n            // Single cell — validate cell reference\n            ParseCellReference(cellRef);\n            var cell = FindCell(data, cellRef);\n            if (cell == null)\n            {","sourceCodeStart":918,"sourceCodeEnd":954,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Query.cs#L918-L954","documentation":"Thrown in the run[N] path when the shared-string item exists and has runs, but the requested 1-based run index N is outside [1, runs.Count]. Run indices are 1-based (converted via PathIndex.ToArrayIndex), so the valid range starts at 1, and the message reports the actual count.","triggerScenarios":"get /Sheet1/A1/run[5] where A1's shared string has only 2 runs; run[0] (below the 1-based floor); any N greater than the number of Run elements in the SharedStringItem.","commonSituations":"Assuming a cell has more formatted runs than it does; off-by-one from zero-based thinking (run[0] is invalid); indexing runs in a loop without first checking the count.","solutions":["Query the run count first (get /Sheet1/A1 and inspect children, or list the cell) and bound N to 1..count.","Use the correct 1-based index (run[1] is the first run, not run[0]).","If you only need the whole cell text, read the cell directly instead of a specific run."],"exampleFix":"// before\nget /Sheet1/A1/run[5]   // A1 has 2 runs\n// after\nget /Sheet1/A1/run[2]   // last valid run (1-based)","handlingStrategy":"validation","validationCode":"# bound the run index by the actual run count\ncell = doc.get('/Sheet1/A1')\nrun_count = len(cell.get('children', [])) if cell.get('type') == 'rich' else 0\nN = 5\nassert 1 <= N <= run_count, f'run index {N} out of range (1-{run_count})'\ndoc.get(f'/Sheet1/A1/run[{N}]')","typeGuard":"def valid_run_index(N, run_count):\n    \"\"\"Run indices are 1-based.\"\"\"\n    return isinstance(N, int) and 1 <= N <= run_count","tryCatchPattern":"null","preventionTips":["Run indices are 1-based — run[1] is the first run, run[0] is invalid.","Query the cell's run count before indexing.","If you only need full text, read the cell rather than a specific run."],"tags":["excel","rich-text","run","out-of-range","get"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}