{"record":{"id":"6d602dac19e8de9b","repo":"iOfficeAI/OfficeCLI","slug":"field-index-idx-out-of-range-0-headers-length","errorCode":null,"errorMessage":"field index {idx} out of range (0..{headers.Length - 1})","messagePattern":"field index (.+?) out of range \\(0\\.\\.(.+?)\\)","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Core/PivotTableHelper.Parse.cs","lineNumber":348,"sourceCode":"            // robust even if the source headers were renamed between Get and\n            // Set, and removes any ambiguity from the prefix-strip heuristic.\n            if (roundTripFieldIdx.HasValue)\n            {\n                if (roundTripFieldIdx.Value < 0 || roundTripFieldIdx.Value >= headers.Length)\n                    throw new ArgumentException(\n                        $\"field index {roundTripFieldIdx.Value} out of range (0..{headers.Length - 1})\");\n                fieldIdx = roundTripFieldIdx.Value;\n            }\n            else if (int.TryParse(fieldName, out var idx))\n            {\n                // CONSISTENCY(strict-enums / R8-6): a numeric token is a\n                // column index. Out-of-range indices used to silently drop\n                // the value-field, producing an empty pivot with no error.\n                // Reject up front with the available-index range so users\n                // catch the typo immediately (mirrors the throw used for\n                // unknown field names).\n                if (idx < 0 || idx >= headers.Length)\n                    throw new ArgumentException(\n                        $\"field index {idx} out of range (0..{headers.Length - 1})\");\n                fieldIdx = idx;\n            }\n            else\n            {\n                for (int i = 0; i < headers.Length; i++)\n                    if (FieldNameMatches(headers[i], fieldName)) { fieldIdx = i; break; }\n                // CONSISTENCY(field-name-validation): non-numeric token must\n                // resolve. Same throw shape as ParseFieldList.\n                if (fieldIdx < 0)\n                {\n                    var available = string.Join(\", \", headers.Where(h => !string.IsNullOrEmpty(h)));\n                    throw new ArgumentException($\"field '{fieldName}' not found in source headers: {available}\");\n                }\n            }\n\n            if (fieldIdx >= 0 && fieldIdx < headers.Length)\n            {","sourceCodeStart":330,"sourceCodeEnd":366,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Core/PivotTableHelper.Parse.cs#L330-L366","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a 0-based index within the reported range: values=4 for the 5th column","Switch to the column name to avoid index math: values=Sales","Confirm the column count of the source range before using positional indices"],"exampleFix":"// before (source has 5 columns, indices 0..4)\nvalues=\"5\"\n// after\nvalues=\"4\"\n// or\nvalues=\"Sales\"","handlingStrategy":"validation","validationCode":"if (int.TryParse(token, out var idx) && (idx < 0 || idx >= headers.Length))\n    throw new InvalidOperationException($\"Index {idx} out of range (0..{headers.Length - 1})\");","typeGuard":"static bool IsInBoundsIndex(string token, int headerCount) =>\n    int.TryParse(token, out var i) && i >= 0 && i < headerCount;","tryCatchPattern":"try { BuildPivot(props); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"out of range\"))\n{ /* correct or replace the numeric token with a field name */ }","preventionTips":["Remember indices are 0-based","Prefer field names over indices when the schema is unclear","Confirm the source column count before using positional indices"],"tags":["pivottable","field-resolution","off-by-one","argument-validation"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}