iOfficeAI/OfficeCLI · error · ArgumentException

field '{fieldName}' not found in source headers: {available}

Error message

field '{fieldName}' not found in source headers: {available}

What it means

The values= counterpart of error 327: a non-numeric field-name token in a value spec could not be matched to any source header. The matching uses the same case-insensitive, trimmed, NFC-normalised FieldNameMatches helper as the rows/cols/filters resolver, so the throw is identical in shape and the message lists the available headers.

Source

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

                // 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)
            {
                // R34-3: a user-supplied 4th (or 3rd-when-no-showAs) segment
                // becomes the DataField.Name (the column header rendered in
                // the pivot output). Falls back to "{Func} of {Header}" when
                // absent — matches Excel's default and preserves the
                // round-trip shape the existing prefix-strip relies on.
                var displayName = !string.IsNullOrEmpty(customName)
                    ? customName!
                    : $"{char.ToUpper(func[0])}{func[1..]} of {headers[fieldIdx]}";
                result.Add((fieldIdx, func, showAs, displayName));
            }
        }
        return result;
    }

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Match the header spelling exactly (see the 'available' list in the message)
  2. If you meant a calculated field, ensure it is added in the same call so it resolves through the calc-field path
  3. Use the column index if the name is unstable

Example fix

// before
values="Revnue:sum"
// after
values="Revenue:sum"
Defensive patterns

Strategy: validation

Validate before calling

var missing = valueFieldNames.Where(n => !headers.Any(h => FieldNameMatches(h, n))).ToList();
if (missing.Count > 0) throw new InvalidOperationException($"Unknown value fields: {string.Join(", ", missing)}");

Type guard

static bool ValueFieldExists(string[] headers, string name) =>
    headers.Any(h => h.Trim().Normalize(NormalizationForm.FormC)
        .Equals(name.Trim().Normalize(NormalizationForm.FormC), StringComparison.OrdinalIgnoreCase));

Try / catch

try { BuildPivot(props); }
catch (ArgumentException ex) when (ex.Message.Contains("not found in source headers"))
{ /* re-prompt with the available list */ }

Prevention

When it happens

Trigger: values=Revnue:sum when the header is 'Revenue'; values=Sale:sum:percent_of_total where 'Sale' is a typo; referencing a calculated-field name before it has been added (calc field names are not source headers).

Common situations: Typos; referencing calc fields by name in values= instead of letting them auto-attach; source columns renamed between sessions; locale-specific spellings.

Related errors

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