iOfficeAI/OfficeCLI · error · ArgumentException

dataField{oneBasedIdx}.showAs: index out of range (1..{dfCou

Error message

dataField{oneBasedIdx}.showAs: index out of range (1..{dfCount} data field(s) defined)

What it means

Thrown in SetPivotTableProperties when the key dataField{N}.showAs=<token> references a 1-based data field index N that exceeds the number of DataFields currently defined on the pivot. The code parses N from between 'dataField' and '.showAs', validates N >= 1, then checks N against the actual DataFields count. This is the write-side counterpart of the Get readback key, letting users copy a key from Get and Set it back.

Source

Thrown at src/officecli/Core/PivotTableHelper.Set.cs:360

                    // R15-4: accept `dataField{N}.showAs=<token>` as the
                    // write-side counterpart of the Get readback key. N is
                    // 1-indexed over the current DataFields list; map to
                    // the positional `showdataas` list so RebuildFieldAreas
                    // can apply the transform through its existing showAs
                    // override path. Consistency with the Get readback
                    // symmetry rule: users copy a key from Get and Set it
                    // back without learning a second vocabulary.
                    var lkDf = key.ToLowerInvariant();
                    if (lkDf.StartsWith("datafield") && lkDf.EndsWith(".showas"))
                    {
                        var idxStr = lkDf.Substring("datafield".Length,
                            lkDf.Length - "datafield".Length - ".showas".Length);
                        if (int.TryParse(idxStr, out var oneBasedIdx) && oneBasedIdx >= 1)
                        {
                            var existingDf = pivotDef.DataFields?.Elements<DataField>().ToList();
                            var dfCount = existingDf?.Count ?? 0;
                            if (oneBasedIdx > dfCount)
                                throw new ArgumentException(
                                    $"dataField{oneBasedIdx}.showAs: index out of range " +
                                    $"(1..{dfCount} data field(s) defined)");

                            // Build / extend the positional showdataas list
                            // so slot oneBasedIdx-1 carries the new token,
                            // leaving earlier slots empty (RebuildFieldAreas
                            // treats empty slot as "keep current").
                            fieldAreaProps.TryGetValue("showdataas", out var existingShow);
                            var slots = existingShow?.Split(',').Select(s => s.Trim()).ToList()
                                        ?? new List<string>();
                            while (slots.Count < oneBasedIdx) slots.Add("");
                            slots[oneBasedIdx - 1] = value;
                            fieldAreaProps["showdataas"] = string.Join(",", slots);

                            // Force RebuildFieldAreas to run even without
                            // any rows/cols/values/filters in this call.
                            if (!fieldAreaProps.ContainsKey("rows") && !fieldAreaProps.ContainsKey("cols")
                                && !fieldAreaProps.ContainsKey("values") && !fieldAreaProps.ContainsKey("filters")

View on GitHub (pinned to 1ced45e900)

Solutions

Run Get pivot first to see how many DataFields are currently defined and their 1-based indices.
Use an index within the range 1..count returned by the DataFields list.
If you need more data fields, add them via values= before referencing the higher index.
Remember the index is 1-based (dataField1 is the first, not dataField0).

Example fix

// before — only 2 data fields exist
Set pivot dataField3.showAs=percentOfTotal
// after — use a valid index, or add the value first
Set pivot values=Revenue,Cost dataField2.showAs=percentOfTotal

Defensive patterns

Strategy: validation

Validate before calling

// Before setting dataField{N}.showAs, check the count
int dfCount = pivotDef.DataFields?.Elements<DataField>().Count() ?? 0;
if (oneBasedIdx < 1 || oneBasedIdx > dfCount)
    throw new ArgumentException($"dataField index {oneBasedIdx} out of range (1..{dfCount}).");

Prevention

Run Get pivot to see the current DataFields list and valid indices.
Remember data field indices are 1-based (dataField1 is the first).
If you need more data fields, add them via values= first.
After removing value fields, update any dataField{N}.showAs references that pointed past the new count.

When it happens

Trigger: Calling Set pivot dataField5.showAs=percentOfTotal when the pivot only has 3 data fields defined (N must be in 1..3). Or referencing an index after a values= change that reduced the data field count.

Common situations: Copying a dataField key from a Get dump of a different/older pivot that had more value fields; stale assumptions about how many values are defined; off-by-one confusion between 0-based and 1-based indexing.

Related errors

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