iOfficeAI/OfficeCLI · error · ArgumentException

Run index {runIdx} out of range (1-{runs.Count})

Error message

Run index {runIdx} out of range (1-{runs.Count})

What it means

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.

Source

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

        // Handle /SheetName/A1/run[N] (rich text run direct access)
        var runGetMatch = Regex.Match(cellRef, @"^([A-Z]+\d+)/run\[(\d+)\]$", RegexOptions.IgnoreCase);
        if (runGetMatch.Success)
        {
            var runCellRef = runGetMatch.Groups[1].Value.ToUpperInvariant();
            var runIdx = int.Parse(runGetMatch.Groups[2].Value);
            ParseCellReference(runCellRef);
            var runCell = FindCell(data, runCellRef);
            if (runCell == null)
                throw new ArgumentException($"Cell {runCellRef} not found");
            if (runCell.DataType?.Value != CellValues.SharedString ||
                !int.TryParse(runCell.CellValue?.Text, out var sstIdx))
                throw new ArgumentException($"Cell {runCellRef} is not a rich text cell");
            var sstPart = _doc.WorkbookPart?.GetPartsOfType<SharedStringTablePart>().FirstOrDefault();
            var ssi = sstPart?.SharedStringTable?.Elements<SharedStringItem>().ElementAtOrDefault(sstIdx);
            if (ssi == null) throw new ArgumentException($"SharedString entry {sstIdx} not found");
            var runs = ssi.Elements<Run>().ToList();
            if (runIdx < 1 || runIdx > runs.Count)
                throw new ArgumentException($"Run index {runIdx} out of range (1-{runs.Count})");
            return RunToNode(runs[PathIndex.ToArrayIndex(runIdx)], $"/{sheetNameFromPath}/{runCellRef}/run[{runIdx}]");
        }

        if (cellRef.Contains(':'))
        {
            // Range — validate both endpoints
            var rangeParts = cellRef.Split(':');
            ParseCellReference(rangeParts[0]);
            if (rangeParts.Length > 1) ParseCellReference(rangeParts[1]);
            return GetCellRange(sheetNameFromPath, data, cellRef, depth, worksheet);
        }
        else
        {
            // Single cell — validate cell reference
            ParseCellReference(cellRef);
            var cell = FindCell(data, cellRef);
            if (cell == null)
            {

View on GitHub (pinned to 1ced45e900)

Solutions

1. Query the run count first (get /Sheet1/A1 and inspect children, or list the cell) and bound N to 1..count.
2. Use the correct 1-based index (run[1] is the first run, not run[0]).
3. If you only need the whole cell text, read the cell directly instead of a specific run.

Example fix

// before
get /Sheet1/A1/run[5]   // A1 has 2 runs
// after
get /Sheet1/A1/run[2]   // last valid run (1-based)

# bound the run index by the actual run count
cell = doc.get('/Sheet1/A1')
run_count = len(cell.get('children', [])) if cell.get('type') == 'rich' else 0
N = 5
assert 1 <= N <= run_count, f'run index {N} out of range (1-{run_count})'
doc.get(f'/Sheet1/A1/run[{N}]')

def valid_run_index(N, run_count):
    """Run indices are 1-based."""
    return isinstance(N, int) and 1 <= N <= run_count

null

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Cell {runCellRef} not found
• Cell {runCellRef} is not a rich text cell
• Invalid cell reference: '{cellRef}'. Expected format like 'A
• {cellRef} spans multiple {(char.IsDigit(cellRef[0]) ? "rows"
• SharedString entry {sstIdx} not found

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