iOfficeAI/OfficeCLI · error · System.ArgumentException

Invalid 'row' value: '{rbRowIdx}'. Row breaks must be betwee

Error message

Invalid 'row' value: '{rbRowIdx}'. Row breaks must be between 1 and 1048576.

What it means

Thrown by AddRowBreak when the parsed row index is less than 1 or greater than 1048576 (the maximum row count in an OOXML worksheet). rbRowIdx is a uint, so negative values cannot occur; the lower bound catches 0 and the upper bound catches anything beyond the grid. Break ids outside the grid fail the schema's Min/Max constraints and Excel rejects the file on open.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Add.Cells.cs:1335

            return Add(parentPath, "colbreak", position, properties);
        return Add(parentPath, "rowbreak", position, properties);
    }

    private string AddRowBreak(string parentPath, string type, InsertPosition? position, Dictionary<string, string> properties)
    {
        var index = position?.Index;
        var rbSegments = parentPath.TrimStart('/').Split('/', 2);
        var rbSheetName = rbSegments[0];
        var rbWorksheet = FindWorksheet(rbSheetName)
            ?? throw new ArgumentException($"Sheet not found: {rbSheetName}");
        var rbWs = GetSheet(rbWorksheet);

        var rbRowIdx = uint.Parse(properties.GetValueOrDefault("row") ?? properties.GetValueOrDefault("index")
            ?? throw new ArgumentException("'row' property is required for rowbreak"));
        // A break id of 0 or beyond the grid fails the schema's Min/Max
        // constraints — reject up front instead of writing invalid OOXML.
        if (rbRowIdx < 1 || rbRowIdx > 1048576)
            throw new ArgumentException(
                $"Invalid 'row' value: '{rbRowIdx}'. Row breaks must be between 1 and 1048576.");

        var rowBreaks = rbWs.GetFirstChild<RowBreaks>();
        if (rowBreaks == null)
        {
            rowBreaks = new RowBreaks();
            rbWs.AppendChild(rowBreaks);
        }
        // Optional restricted column span (min/max) — mirrors the Set path so a
        // dump-emitted `add rowbreak row=N min=.. max=..` reproduces a
        // non-full-width break. Defaults to full width (max 16383) when absent.
        var rbBreak = new Break { Id = rbRowIdx, Max = 16383u, ManualPageBreak = true };
        if (properties.TryGetValue("min", out var rbMinS) && uint.TryParse(rbMinS, out var rbMin))
            rbBreak.Min = rbMin;
        if (properties.TryGetValue("max", out var rbMaxS) && uint.TryParse(rbMaxS, out var rbMax))
            rbBreak.Max = rbMax;
        if (properties.TryGetValue("manual", out var rbMan))
            rbBreak.ManualPageBreak = IsTruthy(rbMan);

View on GitHub (pinned to 1ced45e900)

Solutions

Use a row number between 1 and 1048576 inclusive.
If the value came from a 0-based source, add 1 before passing it.
Clamp computed indices to the valid range and log a warning if clamping changes the value.

Example fix

// before
props["row"] = "0"; // 0-based assumption

// after
props["row"] = "1"; // OOXML rows are 1-based

Defensive patterns

Strategy: validation

Validate before calling

if (!uint.TryParse(props.GetValueOrDefault("row") ?? props.GetValueOrDefault("index"), out var row) || row < 1 || row > 1048576)
    throw new ArgumentOutOfRangeException("row", "must be 1-1048576");
handler.Add("/Sheet1", "rowbreak", null, props);

Type guard

static bool IsValidRow(uint row) => row >= 1 && row <= 1048576;

Prevention

Treat row indices as 1-based everywhere in your script.
Clamp computed row numbers to 1-1048576 and warn on clamping.
Validate numeric parse and range before adding the property.

When it happens

Trigger: properties["row"]="0", properties["row"]="1048577", or a value that parsed as uint but is out of grid range. Note: a non-numeric or overflow value (e.g. "99999999999") fails uint.Parse first with an OverflowException, not this guard. This guard only fires for in-uint-but-out-of-grid values.

Common situations: User computes a row number from data and it underflows to 0. Copying a 1-based vs 0-based assumption. A formula-derived index that exceeds the sheet grid.

Related errors

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