iOfficeAI/OfficeCLI · error · ArgumentException

field index {idx} out of range (0..{headers.Length - 1})

Error message

field index {idx} out of range (0..{headers.Length - 1})

What it means

In ParseValueFields, when a values= token is numeric (no Get-readback shape present), the helper treats it as a column index and requires it to be in range 0..headers.Length-1. Out-of-range numeric tokens used to silently drop, producing an empty pivot with no error; this strict check surfaces the typo immediately, mirroring the policy used for unknown field names.

Source

Thrown at src/officecli/Core/PivotTableHelper.Parse.cs:348

            // robust even if the source headers were renamed between Get and
            // Set, and removes any ambiguity from the prefix-strip heuristic.
            if (roundTripFieldIdx.HasValue)
            {
                if (roundTripFieldIdx.Value < 0 || roundTripFieldIdx.Value >= headers.Length)
                    throw new ArgumentException(
                        $"field index {roundTripFieldIdx.Value} out of range (0..{headers.Length - 1})");
                fieldIdx = roundTripFieldIdx.Value;
            }
            else if (int.TryParse(fieldName, out var idx))
            {
                // CONSISTENCY(strict-enums / R8-6): a numeric token is a
                // column index. Out-of-range indices used to silently drop
                // the value-field, producing an empty pivot with no error.
                // Reject up front with the available-index range so users
                // catch the typo immediately (mirrors the throw used for
                // unknown field names).
                if (idx < 0 || idx >= headers.Length)
                    throw new ArgumentException(
                        $"field index {idx} out of range (0..{headers.Length - 1})");
                fieldIdx = idx;
            }
            else
            {
                for (int i = 0; i < headers.Length; i++)
                    if (FieldNameMatches(headers[i], fieldName)) { fieldIdx = i; break; }
                // CONSISTENCY(field-name-validation): non-numeric token must
                // resolve. Same throw shape as ParseFieldList.
                if (fieldIdx < 0)
                {
                    var available = string.Join(", ", headers.Where(h => !string.IsNullOrEmpty(h)));
                    throw new ArgumentException($"field '{fieldName}' not found in source headers: {available}");
                }
            }

            if (fieldIdx >= 0 && fieldIdx < headers.Length)
            {

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Use a 0-based index within the reported range: values=4 for the 5th column
  2. Switch to the column name to avoid index math: values=Sales
  3. Confirm the column count of the source range before using positional indices

Example fix

// before (source has 5 columns, indices 0..4)
values="5"
// after
values="4"
// or
values="Sales"
Defensive patterns

Strategy: validation

Validate before calling

if (int.TryParse(token, out var idx) && (idx < 0 || idx >= headers.Length))
    throw new InvalidOperationException($"Index {idx} out of range (0..{headers.Length - 1})");

Type guard

static bool IsInBoundsIndex(string token, int headerCount) =>
    int.TryParse(token, out var i) && i >= 0 && i < headerCount;

Try / catch

try { BuildPivot(props); }
catch (ArgumentException ex) when (ex.Message.Contains("out of range"))
{ /* correct or replace the numeric token with a field name */ }

Prevention

When it happens

Trigger: values=99 when the source has only 5 columns; values=5 when there are 5 columns (valid indices are 0..4 — off-by-one); negative indices passed via values=-1.

Common situations: Off-by-one confusion between 1-based Excel column letters and 0-based indices; stale index from a previously wider source; typo or autocomplete inserting the wrong number.

Related errors

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