{"record":{"id":"69b4293c29b9067d","repo":"iOfficeAI/OfficeCLI","slug":"top10-conditional-formatting-requires-rank-1-g","errorCode":null,"errorMessage":"top10 conditional formatting requires rank >= 1 (got {rankInt}).","messagePattern":"top10 conditional formatting requires rank >= 1 \\(got (.+?)\\)\\.","errorType":"validation","errorClass":"System.ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Add.Cf.cs","lineNumber":667,"sourceCode":"            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\":\n            {\n                // `above=` is the legacy spelling; `aboveaverage=false`\n                // (matching the cfType name) is accepted as an alias","sourceCodeStart":649,"sourceCodeEnd":685,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Add.Cf.cs#L649-L685","documentation":"Thrown by the topn (top10) case in AddCfExtended when the parsed rank is a valid integer but <= 0. A top10 rule with rank 0 or negative is meaningless (rank 0 would select zero items) and would produce a cast to uint that misrepresents the intent. The guard runs after the int parse succeeds.","triggerScenarios":"Calling Add with type=topn and a rank/top/bottomN/value property that parses as an integer <= 0. Examples: value=0, value=-5.","commonSituations":"Off-by-one expecting rank 0 to mean 'top item'; negative value from a computed input; default value of 0 from an unset variable in a calling script.","solutions":["Set rank/top/value to an integer >= 1 (e.g. value=1 for the single top item).","Omit the property to accept the default rank of 10.","If the rank is computed, clamp it to a minimum of 1 before passing."],"exampleFix":"// before: value=0\nadd /Sheet1/A1:A10 cf type=topn value=0\n// after\nadd /Sheet1/A1:A10 cf type=topn value=1","handlingStrategy":"validation","validationCode":"var rankStr = properties.GetValueOrDefault(\"rank\") ?? properties.GetValueOrDefault(\"top\")\n    ?? properties.GetValueOrDefault(\"bottomN\") ?? properties.GetValueOrDefault(\"value\") ?? \"10\";\nif (int.TryParse(rankStr, out var r) && r <= 0)\n    throw new ArgumentException($\"top10 rank must be >= 1 (got {r}).\");","typeGuard":"static bool IsPositiveTop10Rank(string? s) => !int.TryParse(s, out var r) || r >= 1;","tryCatchPattern":"try { return Add(path, \"topn\", pos, props); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"rank >= 1\"))\n{ props[\"value\"] = \"1\"; return Add(path, \"topn\", pos, props); }","preventionTips":["Ensure rank is an integer >= 1.","Clamp computed ranks to a minimum of 1.","Omit the property for the default of 10."],"tags":["excel","conditional-formatting","top10","range-validation","argument-validation"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}