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.

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 contains invalid control characters
• pivot name must not be empty
• pivot name must not be whitespace-only
• invalid layout: ' '. Valid: compact, outline, tabular
• invalid sort: ' '. Valid: asc, desc, locale, locale-desc

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

Appendix: 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)