iOfficeAI/OfficeCLI · error · ArgumentException

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

Error message

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

What it means

Thrown by ParseFieldList when resolving row/col/filter field tokens: a non-numeric token could not be matched against any source header (after the date-grouping suffix-strip fallback also failed). The error message lists the available non-empty headers so the user can spot the typo. Matching is case-insensitive, trims surrounding whitespace, and normalises Unicode to NFC before comparing, so genuine spelling/normalisation differences are already accounted for.

Source

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

            // CONSISTENCY(date-grouping-passthrough): unrecognized grouping
            // suffixes (e.g. "Date:hours") survive ApplyDateGrouping as
            // literals. Strip the suffix and re-resolve so the bare field
            // name still binds — matches the existing best-effort fuzz
            // contract that says invalid grouping must not crash.
            if (found < 0)
            {
                var colon = name.IndexOf(':');
                if (colon > 0)
                {
                    var bare = name.Substring(0, colon);
                    for (int i = 0; i < headers.Length; i++)
                        if (FieldNameMatches(headers[i], bare)) { found = i; break; }
                }
            }
            if (found < 0)
            {
                var available = string.Join(", ", headers.Where(h => !string.IsNullOrEmpty(h)));
                throw new ArgumentException($"field '{name}' not found in source headers: {available}");
            }
            if (seen.Add(found)) result.Add(found);
        }
        return result;
    }

    private static List<(int idx, string func, string showAs, string name)> ParseValueFields(
        Dictionary<string, string> props, string key, string[] headers)
    {
        if (!props.TryGetValue(key, out var value) || string.IsNullOrEmpty(value))
            return new List<(int, string, string, string)>();

        // CONSISTENCY(aggregate-override): the optional sibling 'aggregate'
        // property is a comma-list aligned positionally with 'values'. It
        // overrides the per-field func parsed from the colon-suffix syntax.
        // This lets users write `values=Sales,Sales aggregate=sum,count`
        // instead of `values=Sales:sum,Sales:count` — both forms are
        // equivalent. Per-spec colon syntax still wins for any slot the

View on GitHub (pinned to 1ced45e900)

Solutions

1. Read the 'available' list in the error and correct the spelling to match exactly
2. Re-check the source range header row (the first row of the pivot source) for the actual column name
3. If you want positional addressing, pass the column index instead of the name

Example fix

// before
rows="Regin,Product"
// after
rows="Region,Product"

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

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

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

When it happens

Trigger: rows=Regin when the header is 'Region'; cols=PostlCode (typo); a field name with a CJK/Unicode variant that even NFC normalisation cannot reconcile; using a display label that differs from the underlying header.

Common situations: Typos in CLI input; renamed source columns the user has not noticed; mismatched locale/normalisation between data export and pivot input; reference to a column that lives in a different sheet than the source range.

Related errors

• calculatedField requires a non-empty name
• calculatedField '{name}' requires a non-empty formula
• calculatedField '{raw}' must be 'Name:=Formula' (colon-separ
• field index {roundTripFieldIdx.Value} out of range (0..{head
• field index {idx} out of range (0..{headers.Length - 1})

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