iOfficeAI/OfficeCLI · error · ArgumentException

calculatedField '{raw}' must be 'Name:=Formula' (colon-separ

Error message

calculatedField '{raw}' must be 'Name:=Formula' (colon-separated)

What it means

The bare or numbered 'calculatedField' / 'calculatedField1' / 'calculatedField2' props use a colon-separated 'Name:=Formula' syntax. If the value has no colon at all, the parser cannot split name from formula and rejects it with this message. Note: a literal colon inside the formula after the first one is fine, because only IndexOf(':') (the first colon) is used as the split point.

Source

Thrown at src/officecli/Core/PivotTableHelper.Definition.cs:1749

            {
                throw new ArgumentException($"invalid JSON for calculatedFields: {ex.Message}");
            }
        }

        // Numbered + bare calculatedField props (ordinal sort so calculatedField1
        // appears before calculatedField2 regardless of insertion order).
        var cfKeys = properties.Keys
            .Where(k => System.Text.RegularExpressions.Regex.IsMatch(
                k, @"^calculatedField\d*$", System.Text.RegularExpressions.RegexOptions.IgnoreCase))
            .OrderBy(k => k, StringComparer.OrdinalIgnoreCase)
            .ToList();
        foreach (var key in cfKeys)
        {
            var raw = properties[key];
            if (string.IsNullOrWhiteSpace(raw)) continue;
            var colonIdx = raw.IndexOf(':');
            if (colonIdx < 0)
                throw new ArgumentException(
                    $"calculatedField '{raw}' must be 'Name:=Formula' (colon-separated)");
            var name = raw[..colonIdx].Trim();
            var formula = raw[(colonIdx + 1)..].Trim();
            result.Add((name, formula));
        }

        return result;
    }

}

View on GitHub (pinned to 1ced45e900)

Solutions

Use the colon form: calculatedField=Margin:=Sales-Cost
For multiple fields, use numbered props: calculatedField1=Margin:=Sales-Cost and calculatedField2=Tax:=Margin*0.2
Switch to JSON form (calculatedFields=[{...}]) if your names or formulas contain colons

Example fix

// before
calculatedField="SalesFormula=A1*2"
// after
calculatedField="SalesFormula:=A1*2"

Defensive patterns

Strategy: validation

Validate before calling

foreach (var (key, raw) in cfProps)
    if (string.IsNullOrWhiteSpace(raw) || raw.IndexOf(':') < 0)
        throw new InvalidOperationException($"{key} must be 'Name:=Formula'");

Type guard

static bool IsColonFormSpec(string raw) =>
    !string.IsNullOrWhiteSpace(raw) && raw.IndexOf(':') >= 0;

Try / catch

try { AddCalculatedFields(props); }
catch (ArgumentException ex) when (ex.Message.Contains("colon-separated"))
{ /* rewrite with the 'Name:=Formula' shape */ }

Prevention

Use ':' (not '=') to separate name and formula
Switch to JSON form if names or formulas contain colons
Validate the colon presence in your own input layer

When it happens

Trigger: calculatedField=SalesFormula (no colon); calculatedField=Sales=A1*2 (used '=' instead of ':' as separator); calculatedField1 with whitespace-only content that lost its colon; copy-paste from Excel's formula bar where ':' was dropped.

Common situations: User assumes '=' separates name and formula (it actually starts the formula half after the colon); a templating step stripped the colon; mismatch with the documented Name:=Formula contract.

Related errors

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