{"record":{"id":"e2f87b5a12f11723","repo":"iOfficeAI/OfficeCLI","slug":"invalid-row-value-rbrowidx-row-breaks-must","errorCode":null,"errorMessage":"Invalid 'row' value: '{rbRowIdx}'. Row breaks must be between 1 and 1048576.","messagePattern":"Invalid 'row' value: '(.+?)'\\. Row breaks must be between 1 and 1048576\\.","errorType":"validation","errorClass":"System.ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Add.Cells.cs","lineNumber":1335,"sourceCode":"            return Add(parentPath, \"colbreak\", position, properties);\n        return Add(parentPath, \"rowbreak\", position, properties);\n    }\n\n    private string AddRowBreak(string parentPath, string type, InsertPosition? position, Dictionary<string, string> properties)\n    {\n        var index = position?.Index;\n        var rbSegments = parentPath.TrimStart('/').Split('/', 2);\n        var rbSheetName = rbSegments[0];\n        var rbWorksheet = FindWorksheet(rbSheetName)\n            ?? throw new ArgumentException($\"Sheet not found: {rbSheetName}\");\n        var rbWs = GetSheet(rbWorksheet);\n\n        var rbRowIdx = uint.Parse(properties.GetValueOrDefault(\"row\") ?? properties.GetValueOrDefault(\"index\")\n            ?? throw new ArgumentException(\"'row' property is required for rowbreak\"));\n        // A break id of 0 or beyond the grid fails the schema's Min/Max\n        // constraints — reject up front instead of writing invalid OOXML.\n        if (rbRowIdx < 1 || rbRowIdx > 1048576)\n            throw new ArgumentException(\n                $\"Invalid 'row' value: '{rbRowIdx}'. Row breaks must be between 1 and 1048576.\");\n\n        var rowBreaks = rbWs.GetFirstChild<RowBreaks>();\n        if (rowBreaks == null)\n        {\n            rowBreaks = new RowBreaks();\n            rbWs.AppendChild(rowBreaks);\n        }\n        // Optional restricted column span (min/max) — mirrors the Set path so a\n        // dump-emitted `add rowbreak row=N min=.. max=..` reproduces a\n        // non-full-width break. Defaults to full width (max 16383) when absent.\n        var rbBreak = new Break { Id = rbRowIdx, Max = 16383u, ManualPageBreak = true };\n        if (properties.TryGetValue(\"min\", out var rbMinS) && uint.TryParse(rbMinS, out var rbMin))\n            rbBreak.Min = rbMin;\n        if (properties.TryGetValue(\"max\", out var rbMaxS) && uint.TryParse(rbMaxS, out var rbMax))\n            rbBreak.Max = rbMax;\n        if (properties.TryGetValue(\"manual\", out var rbMan))\n            rbBreak.ManualPageBreak = IsTruthy(rbMan);","sourceCodeStart":1317,"sourceCodeEnd":1353,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Add.Cells.cs#L1317-L1353","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nprops[\"row\"] = \"0\"; // 0-based assumption\n\n// after\nprops[\"row\"] = \"1\"; // OOXML rows are 1-based","handlingStrategy":"validation","validationCode":"if (!uint.TryParse(props.GetValueOrDefault(\"row\") ?? props.GetValueOrDefault(\"index\"), out var row) || row < 1 || row > 1048576)\n    throw new ArgumentOutOfRangeException(\"row\", \"must be 1-1048576\");\nhandler.Add(\"/Sheet1\", \"rowbreak\", null, props);","typeGuard":"static bool IsValidRow(uint row) => row >= 1 && row <= 1048576;","tryCatchPattern":null,"preventionTips":["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."],"tags":["excel","ooxml","rowbreak","range-validation","argument"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}