iOfficeAI/OfficeCLI · error · ArgumentException

pivot name must not be whitespace-only

Error message

pivot name must not be whitespace-only

What it means

Thrown by ValidatePivotName when the name is non-empty but consists entirely of whitespace characters (Trim() yields length 0). OOXML pivot names are trimmed before use, so a whitespace-only string is effectively blank. This is R8-4: whitespace-only names are explicitly rejected rather than silently accepted.

Source

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

    /// <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
    /// property whose NORMALIZED key is not in this set is reported as
    /// UNSUPPORTED (Add: stderr warning; Set: returned unsupported list).
    /// Must stay in sync with the switch in SetPivotTableProperties and
    /// every properties lookup in CreatePivotTable.

View on GitHub (pinned to 1ced45e900)

Solutions

1. Provide a name with at least one non-whitespace character.
2. Trim user input in your own code and reject it if empty after trimming.
3. Substitute a meaningful default name when the input trims to empty.

Example fix

// before
Set pivot name='   '
// after
Set pivot name='SalesPivot'

if (string.IsNullOrWhiteSpace(pivotName))
    throw new ArgumentException("Pivot name must not be empty or whitespace-only.");

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

When it happens

Trigger: Calling Add pivot name=' ' or Set pivot name='\t' where the entire string is spaces, tabs, or other whitespace.

Common situations: User input that is just spaces; copy-paste that introduced only whitespace; form field left as spaces instead of empty; tab characters passed as the name.

Related errors

• pivot name must not be empty
• 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/70c6a6c47af5bad7. Report an issue: GitHub.