iOfficeAI/OfficeCLI · error · ArgumentException

pivot name contains invalid control characters

Error message

pivot name contains invalid control characters

What it means

Thrown by ValidatePivotName when the trimmed name contains any ASCII control character (code point < 0x20, or 0x7F DEL). These characters are invalid in OOXML display names and would corrupt the XML or render as garbage in Excel's pivot table name field. This is R8-5.

Source

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

    /// (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.
    /// </summary>
    private static readonly HashSet<string> _knownPivotKeys =
        new(StringComparer.OrdinalIgnoreCase)
        {
            "source", "src", "name", "position", "pos", "style",

View on GitHub (pinned to 1ced45e900)

Solutions

1. Strip or replace control characters from the name before passing it.
2. Sanitize user input by removing characters below 0x20 and 0x7F.
3. Use plain ASCII or Unicode printable text for pivot names.

Example fix

// before — contains a tab character
Set pivot name='Sales\tPivot'
// after
Set pivot name='Sales Pivot'

if (pivotName.Any(ch => ch < 0x20 || ch == 0x7F))
    throw new ArgumentException("Pivot name contains invalid control characters.");

static bool HasNoControlChars(string name) =>
    name.All(ch => ch >= 0x20 && ch != 0x7F);

When it happens

Trigger: Calling Add/Set pivot name with embedded control characters such as tab (\t), newline (\n), carriage return (\r), or DEL. These can sneak in from copy-paste, unescaped user input, or binary data interpreted as a string.

Common situations: Name pasted from a source that includes hidden control characters; newline injected via a multi-line input field; binary/encoding issue producing control bytes; tab characters from spreadsheet cell references.

Related errors

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