iOfficeAI/OfficeCLI · error · ArgumentException

PivotTable index {ptIdx} out of range (1-{pivotParts.Count})

Error message

PivotTable index {ptIdx} out of range (1-{pivotParts.Count})

What it means

Thrown for /Sheet/pivottable[N] when N exceeds worksheet.PivotTableParts.Count (1-based). Each worksheet owns its own pivot-table parts; the valid per-sheet range is shown in the message.

Source

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

                var seriesIdx = int.Parse(chartMatch.Groups[2].Value);
                var seriesChildren = chartNode.Children.Where(c => c.Type == "series").ToList();
                if (seriesIdx < 1 || seriesIdx > seriesChildren.Count)
                    throw new ArgumentException($"Series {seriesIdx} not found (total: {seriesChildren.Count})");
                var seriesNode = seriesChildren[seriesIdx - 1];
                seriesNode.Path = path;
                return seriesNode;
            }
            return chartNode;
        }

        // Pivot table path: /Sheet1/pivottable[N]
        var pivotMatch = Regex.Match(cellRef, @"^pivottable\[(\d+)\]$", RegexOptions.IgnoreCase);
        if (pivotMatch.Success)
        {
            var ptIdx = int.Parse(pivotMatch.Groups[1].Value);
            var pivotParts = worksheet.PivotTableParts.ToList();
            if (ptIdx < 1 || ptIdx > pivotParts.Count)
                throw new ArgumentException($"PivotTable index {ptIdx} out of range (1-{pivotParts.Count})");

            var pivotPart = pivotParts[ptIdx - 1];
            var ptNode = new DocumentNode { Path = path, Type = "pivottable" };
            if (pivotPart.PivotTableDefinition != null)
                PivotTableHelper.ReadPivotTableProperties(pivotPart.PivotTableDefinition, ptNode, pivotPart);
            return ptNode;
        }

        // Slicer path: /Sheet1/slicer[N]
        var slicerMatch = Regex.Match(cellRef, @"^slicer\[(\d+)\]$", RegexOptions.IgnoreCase);
        if (slicerMatch.Success)
        {
            var slIdx = int.Parse(slicerMatch.Groups[1].Value);
            if (!TryFindSlicerByIndex(worksheet, slIdx, out var slicerElem, out var slicerCache) || slicerElem == null)
                throw new ArgumentException($"slicer[{slIdx}] not found on sheet '{sheetNameFromPath}'");
            var slNode = new DocumentNode { Path = path, Type = "slicer" };
            ReadSlicerProperties(slicerElem, slicerCache, slNode);
            return slNode;

View on GitHub (pinned to 1ced45e900)

Solutions

1. Use a 1-based index in [1, pivotCount].
2. Verify the sheet has pivot tables before indexing.
3. try/catch(ArgumentException) and read the (1-N) range from the message.

Example fix

// before
var pt = handler.Get("/Sheet1/pivottable[2]"); // throws if <2 pivots

// after
try { var pt = handler.Get("/Sheet1/pivottable[2]"); }
catch (ArgumentException) { /* pivot index invalid */ }

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("/Sheet1/pivottable[2]"); }
catch (ArgumentException ex) { /* ex.Message carries the valid (1-N) range */ return null; }

When it happens

Trigger: handler.Get("/Sheet1/pivottable[2]") on a sheet with one (or zero) pivot tables. pivottable[0].

Common situations: Hard-coded pivot index on a sheet whose pivots were removed. Wrong sheet. Zero-based indexing.

Related errors

• Row break index {rbIdx} out of range (1-{breaks.Count})
• Column break index {cbIdx} 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})

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