{"record":{"id":"83d9d876995d2063","repo":"iOfficeAI/OfficeCLI","slug":"pivot-name-exceeds-255-character-limit","errorCode":null,"errorMessage":"pivot name exceeds 255-character limit","messagePattern":"pivot name exceeds 255-character limit","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Core/PivotTableHelper.cs","lineNumber":190,"sourceCode":"    /// </summary>\n    private static string ValidatePivotName(string name)\n    {\n        // Empty string is rejected — a blank name is always an error.\n        if (string.IsNullOrEmpty(name))\n            throw new ArgumentException(\"pivot name must not be empty\");\n        var trimmed = name.Trim();\n        // Whitespace-only names are rejected — R8-4.\n        if (trimmed.Length == 0)\n            throw new ArgumentException(\"pivot name must not be whitespace-only\");\n        // ASCII control characters are rejected — R8-5.\n        foreach (var ch in trimmed)\n        {\n            if (ch < 0x20 || ch == 0x7F)\n                throw new ArgumentException(\"pivot name contains invalid control characters\");\n        }\n        // 255-character limit — R11-4.\n        if (trimmed.Length > 255)\n            throw new ArgumentException(\"pivot name exceeds 255-character limit\");\n        return trimmed;\n    }\n\n    /// <summary>\n    /// Canonical key set recognized by the pivot Add / Set pipeline. Any\n    /// property whose NORMALIZED key is not in this set is reported as\n    /// UNSUPPORTED (Add: stderr warning; Set: returned unsupported list).\n    /// Must stay in sync with the switch in SetPivotTableProperties and\n    /// every properties lookup in CreatePivotTable.\n    /// </summary>\n    private static readonly HashSet<string> _knownPivotKeys =\n        new(StringComparer.OrdinalIgnoreCase)\n        {\n            \"source\", \"src\", \"name\", \"position\", \"pos\", \"style\",\n            \"rows\", \"cols\", \"filters\", \"values\",\n            \"aggregate\", \"showdataas\", \"topn\",\n            \"sort\", \"layout\", \"repeatlabels\", \"blankrows\", \"grandtotalcaption\",\n            \"grandtotals\", \"rowgrandtotals\", \"colgrandtotals\",","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Core/PivotTableHelper.cs#L172-L208","documentation":"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.","triggerScenarios":"Calling Add/Set pivot name with a string longer than 255 characters after trimming.","commonSituations":"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.","solutions":["Shorten the name to 255 characters or fewer.","If the name is auto-generated, truncate it and append a short hash/suffix for uniqueness.","Validate name length before calling Add/Set."],"exampleFix":"// before — name is 300 chars\nSet pivot name='<very long string>'\n// after — truncate to <= 255\nSet pivot name='<short name>'","handlingStrategy":"validation","validationCode":"if (pivotName.Trim().Length > 255)\n    throw new ArgumentException(\"Pivot name exceeds 255-character limit.\");","typeGuard":"static bool IsWithinNameLimit(string name) => name.Trim().Length <= 255;","tryCatchPattern":null,"preventionTips":["Keep pivot names under 255 characters.","If auto-generating names from concatenated data, truncate and add a short suffix.","Validate length before calling Add/Set."],"tags":["pivot","excel","naming","validation","length-limit"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}