iOfficeAI/OfficeCLI · error · ArgumentException

pivot name exceeds 255-character limit

Error message

pivot name exceeds 255-character limit

What it means

Thrown by ValidatePivotName when the trimmed name exceeds 255 characters. This is the OOXML/Excel hard limit on pivot table name length (R11-4). Names longer than 255 characters cannot be stored in the Name attribute and would be rejected by Excel on open.

Source

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

    /// </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",
            "rows", "cols", "filters", "values",
            "aggregate", "showdataas", "topn",
            "sort", "layout", "repeatlabels", "blankrows", "grandtotalcaption",
            "grandtotals", "rowgrandtotals", "colgrandtotals",

View on GitHub (pinned to 1ced45e900)

Solutions

1. Shorten the name to 255 characters or fewer.
2. If the name is auto-generated, truncate it and append a short hash/suffix for uniqueness.
3. Validate name length before calling Add/Set.

Example fix

// before — name is 300 chars
Set pivot name='<very long string>'
// after — truncate to <= 255
Set pivot name='<short name>'

if (pivotName.Trim().Length > 255)
    throw new ArgumentException("Pivot name exceeds 255-character limit.");

static bool IsWithinNameLimit(string name) => name.Trim().Length <= 255;

When it happens

Trigger: Calling Add/Set pivot name with a string longer than 255 characters after trimming.

Common situations: Programmatically generating very long names from concatenated fields; pasting a long block of text; a name derived from a cell range reference or formula that grew unbounded.

Related errors

• pivot name must not be empty
• pivot name must not be whitespace-only
• pivot name contains invalid control characters
• 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/83d9d876995d2063. Report an issue: GitHub.