iOfficeAI/OfficeCLI · error · System.ArgumentException

top10 conditional formatting requires an integer rank (got '

Error message

top10 conditional formatting requires an integer rank (got '{rankStr}'). Use top=N or value=N.

What it means

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.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Add.Cf.cs:664

        // properties["type"] (the user-facing switch; the outer `type`
        // variable is literal "cfextended" here).
        if (typeLower == "cfextended")
            typeLower = (properties.GetValueOrDefault("type", "") ?? "").ToLowerInvariant();

        switch (typeLower)
        {
            case "topn":
            {
                // Accept `rank=` (OOXML attribute name), `top=`/`bottomN=` (legacy
                // aliases), and `value=` (R26-1: matches the cellIs vocabulary so
                // users don't have to learn separate names per CF subtype).
                var rankStr = properties.GetValueOrDefault("rank")
                    ?? properties.GetValueOrDefault("top")
                    ?? properties.GetValueOrDefault("bottomN")
                    ?? properties.GetValueOrDefault("value")
                    ?? "10";
                if (!int.TryParse(rankStr, out var rankInt))
                    throw new ArgumentException(
                        $"top10 conditional formatting requires an integer rank (got '{rankStr}'). Use top=N or value=N.");
                if (rankInt <= 0)
                    throw new ArgumentException(
                        $"top10 conditional formatting requires rank >= 1 (got {rankInt}).");
                var rank = (uint)rankInt;
                var percent = ParseHelpers.IsTruthy(properties.GetValueOrDefault("percent", "false"));
                var bottom = ParseHelpers.IsTruthy(properties.GetValueOrDefault("bottom", "false"));
                cfNewRule = new ConditionalFormattingRule
                {
                    Type = ConditionalFormatValues.Top10,
                    Priority = cfNewPriority,
                    Rank = rank,
                    Percent = percent ? true : null,
                    Bottom = bottom ? true : null
                };
                break;
            }
            case "aboveaverage":

View on GitHub (pinned to 1ced45e900)

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.

Example fix

// before: value=top
add /Sheet1/A1:A10 cf type=topn value=top
// after
add /Sheet1/A1:A10 cf type=topn value=10

Defensive patterns

Strategy: validation

Validate before calling

var rankStr = properties.GetValueOrDefault("rank") ?? properties.GetValueOrDefault("top")
    ?? properties.GetValueOrDefault("bottomN") ?? properties.GetValueOrDefault("value") ?? "10";
if (!int.TryParse(rankStr, out _))
    throw new ArgumentException($"top10 rank '{rankStr}' is not an integer.");

Type guard

static bool IsValidTop10Rank(string? s) => s is null || int.TryParse(s, out _);

Try / catch

try { return Add(path, "topn", pos, props); }
catch (ArgumentException ex) when (ex.Message.Contains("integer rank"))
{ props["value"] = "10"; return Add(path, "topn", pos, props); }

Prevention

Pass a plain integer for rank/top/value.
Omit the property to accept the default 10.
Avoid fractional values, words, or cell references.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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