iOfficeAI/OfficeCLI · error · ArgumentException

pivot name must not be empty

Error message

pivot name must not be empty

What it means

Thrown by ValidatePivotName when the supplied pivot name is null or an empty string. Every pivot table in OOXML requires a non-empty Name attribute. This validation is shared between CreatePivotTable (Add) and SetPivotTableProperties (Set name=) so both paths enforce the same rule (R16-2 extracted it for reuse after Set previously accepted empty names unchecked).

Source

Thrown at src/officecli/Core/PivotTableHelper.cs:177

        if (string.IsNullOrEmpty(key)) return key;
        var lower = key.ToLowerInvariant();
        return _pivotKeyAliases.TryGetValue(lower, out var canonical) ? canonical : lower;
    }

    /// <summary>
    /// Validate a user-supplied pivot table name and return the trimmed value.
    /// Throws ArgumentException for empty, whitespace-only, control-character,
    /// or over-255-character names. Does NOT check workbook-level uniqueness
    /// (that is the caller's responsibility).
    /// R16-2: extracted from CreatePivotTable so SetPivotTableProperties can
    /// reuse the same validation — previously Set accepted empty/whitespace
    /// names without any check.
    /// </summary>
    private static string ValidatePivotName(string name)
    {
        // Empty string is rejected — a blank name is always an error.
        if (string.IsNullOrEmpty(name))
            throw new ArgumentException("pivot name must not be empty");
        var trimmed = name.Trim();
        // Whitespace-only names are rejected — R8-4.
        if (trimmed.Length == 0)
            throw new ArgumentException("pivot name must not be whitespace-only");
        // ASCII control characters are rejected — R8-5.
        foreach (var ch in trimmed)
        {
            if (ch < 0x20 || ch == 0x7F)
                throw new ArgumentException("pivot name contains invalid control characters");
        }
        // 255-character limit — R11-4.
        if (trimmed.Length > 255)
            throw new ArgumentException("pivot name exceeds 255-character limit");
        return trimmed;
    }

    /// <summary>
    /// Canonical key set recognized by the pivot Add / Set pipeline. Any

View on GitHub (pinned to 1ced45e900)

Solutions

1. Provide a non-empty, non-whitespace name for the pivot table.
2. If generating names programmatically, default to a derived name when the input is empty.
3. Validate the name field in your own code before calling Add or Set.

Example fix

// before
Add pivot source=Sheet1!A1:D10 name=''
// after
Add pivot source=Sheet1!A1:D10 name='SalesPivot'

if (string.IsNullOrEmpty(pivotName))
    throw new ArgumentException("Pivot name must not be empty.");

static bool IsValidPivotName(string name) => !string.IsNullOrEmpty(name) && name.Trim().Length > 0;

When it happens

Trigger: Calling Add pivot name='' or Set pivot name='' with an empty string. Or passing a null/empty name property through the properties dictionary.

Common situations: Forgetting to include name= in an Add call when the pipeline requires it; programmatic generation that passes an empty string when a name field was blank in a config; passing name= with no value.

Related errors

• pivot name must not be whitespace-only
• pivot name contains invalid control characters
• pivot name exceeds 255-character limit
• invalid sort: '{mode}'. Valid: asc, desc, locale, locale-des
• Invalid subtotals '{s}'. Valid: on, off (default on)

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