{"record":{"id":"489916f49229434f","repo":"iOfficeAI/OfficeCLI","slug":"top10-conditional-formatting-requires-an-integer-r","errorCode":null,"errorMessage":"top10 conditional formatting requires an integer rank (got '{rankStr}'). Use top=N or value=N.","messagePattern":"top10 conditional formatting requires an integer rank \\(got '(.+?)'\\)\\. Use top=N or value=N\\.","errorType":"validation","errorClass":"System.ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Add.Cf.cs","lineNumber":664,"sourceCode":"        // properties[\"type\"] (the user-facing switch; the outer `type`\n        // variable is literal \"cfextended\" here).\n        if (typeLower == \"cfextended\")\n            typeLower = (properties.GetValueOrDefault(\"type\", \"\") ?? \"\").ToLowerInvariant();\n\n        switch (typeLower)\n        {\n            case \"topn\":\n            {\n                // Accept `rank=` (OOXML attribute name), `top=`/`bottomN=` (legacy\n                // aliases), and `value=` (R26-1: matches the cellIs vocabulary so\n                // users don't have to learn separate names per CF subtype).\n                var rankStr = properties.GetValueOrDefault(\"rank\")\n                    ?? properties.GetValueOrDefault(\"top\")\n                    ?? properties.GetValueOrDefault(\"bottomN\")\n                    ?? properties.GetValueOrDefault(\"value\")\n                    ?? \"10\";\n                if (!int.TryParse(rankStr, out var rankInt))\n                    throw new ArgumentException(\n                        $\"top10 conditional formatting requires an integer rank (got '{rankStr}'). Use top=N or value=N.\");\n                if (rankInt <= 0)\n                    throw new ArgumentException(\n                        $\"top10 conditional formatting requires rank >= 1 (got {rankInt}).\");\n                var rank = (uint)rankInt;\n                var percent = ParseHelpers.IsTruthy(properties.GetValueOrDefault(\"percent\", \"false\"));\n                var bottom = ParseHelpers.IsTruthy(properties.GetValueOrDefault(\"bottom\", \"false\"));\n                cfNewRule = new ConditionalFormattingRule\n                {\n                    Type = ConditionalFormatValues.Top10,\n                    Priority = cfNewPriority,\n                    Rank = rank,\n                    Percent = percent ? true : null,\n                    Bottom = bottom ? true : null\n                };\n                break;\n            }\n            case \"aboveaverage\":","sourceCodeStart":646,"sourceCodeEnd":682,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Add.Cf.cs#L646-L682","documentation":"Thrown by the topn (top10) case in AddCfExtended when the rank value cannot be parsed as an int. The rank is read from 'rank', 'top', 'bottomN', or 'value' (default '10'). int.TryParse fails on non-integer input. The OOXML Rank attribute is an unsigned int, so a non-numeric or fractional value is rejected before it reaches the XML.","triggerScenarios":"Calling Add with type=topn/top10/top (or cf type=topn) and a rank/top/bottomN/value property that is not an integer string. Examples: value=top, value=5.5, value=three.","commonSituations":"Passing a fractional rank (Excel requires integer); passing a word; passing a range reference instead of a count; locale decimal separator (comma) breaking the parse.","solutions":["Provide an integer for rank/top/value (e.g. value=10).","Omit the property to accept the default rank of 10.","Ensure the value is a plain integer string, not a formula or reference."],"exampleFix":"// before: value=top\nadd /Sheet1/A1:A10 cf type=topn value=top\n// after\nadd /Sheet1/A1:A10 cf type=topn value=10","handlingStrategy":"validation","validationCode":"var rankStr = properties.GetValueOrDefault(\"rank\") ?? properties.GetValueOrDefault(\"top\")\n    ?? properties.GetValueOrDefault(\"bottomN\") ?? properties.GetValueOrDefault(\"value\") ?? \"10\";\nif (!int.TryParse(rankStr, out _))\n    throw new ArgumentException($\"top10 rank '{rankStr}' is not an integer.\");","typeGuard":"static bool IsValidTop10Rank(string? s) => s is null || int.TryParse(s, out _);","tryCatchPattern":"try { return Add(path, \"topn\", pos, props); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"integer rank\"))\n{ props[\"value\"] = \"10\"; return Add(path, \"topn\", pos, props); }","preventionTips":["Pass a plain integer for rank/top/value.","Omit the property to accept the default 10.","Avoid fractional values, words, or cell references."],"tags":["excel","conditional-formatting","top10","numeric-validation","argument-validation"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}