iOfficeAI/OfficeCLI · error · ArgumentException

Invalid 'outline' value: '{addRowOutline}'. Expected an inte

Error message

Invalid 'outline' value: '{addRowOutline}'. Expected an integer 0-7 (outline/group level).

What it means

Excel's outline/group level is stored as a byte 0-7 (the OOXML `outlineLevel` attribute). AddRow accepts the value via the `outline`, `outlinelevel`, or `group` property aliases. This guard parses it as a byte and rejects anything outside 0-7 before the structural ShiftRowsDown runs — validating before the shift (atomicity rule) prevents a half-applied row shift on a failed add.

Source

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

        // down. Gate only on "inserting at a position" (index set), NOT on the
        // presence of cell data at/below — sheet-level structures (CF / merge /
        // dataValidation) anchored on still-empty cells must shift too. Mirrors
        // AddCol, which calls ShiftColumnsRight on every positional insert
        // (CONSISTENCY(add-row-col-shift)). When nothing sits at/below rowIdx this
        // is a harmless no-op.
        // Validate all props BEFORE the structural shift (same atomicity rule
        // as AddCol): a height/outline parse failure after ShiftRowsDown left
        // the shift applied even though the add reported an error.
        double? parsedRowHeight = null;
        if (properties.TryGetValue("height", out var addRowHeight) && !string.IsNullOrWhiteSpace(addRowHeight))
            parsedRowHeight = ParseRowHeightPoints(addRowHeight);
        byte? parsedRowOutline = null;
        if (properties.TryGetValue("outline", out var addRowOutline)
            || properties.TryGetValue("outlinelevel", out addRowOutline)
            || properties.TryGetValue("group", out addRowOutline))
        {
            if (!byte.TryParse(addRowOutline, out var addRowOutlineVal) || addRowOutlineVal > 7)
                throw new ArgumentException($"Invalid 'outline' value: '{addRowOutline}'. Expected an integer 0-7 (outline/group level).");
            parsedRowOutline = addRowOutlineVal;
        }

        bool needsShift = index.HasValue;
        if (needsShift)
            ShiftRowsDown(worksheet, rowIdx);

        var newRow = new Row { RowIndex = (uint)rowIdx };

        // CONSISTENCY(add-set-symmetry): accept height/hidden at creation
        // time, mirroring SetRow semantics (ExcelHandler.Set.cs L3157-3164).
        if (parsedRowHeight is { } rh)
        {
            newRow.Height = rh;
            newRow.CustomHeight = true;
        }
        if (properties.TryGetValue("hidden", out var addRowHidden))
        {

View on GitHub (pinned to 1ced45e900)

Solutions

1. Use an integer 0-7 where 0 = no grouping and 7 = deepest nested level.
2. If your source data has >7 levels, collapse the extra levels into the 7 cap before adding the row.
3. Ensure the value is a plain integer string (no sign, no decimal) — it is parsed as an unsigned byte.

Example fix

// before
handler.Add("/Sheet1", "row", null, new() { ["outline"] = "8" });
// after
handler.Add("/Sheet1", "row", null, new() { ["outline"] = "7" });

if (!byte.TryParse(outlineStr, out var lvl) || lvl > 7)
    throw new ArgumentException("outline must be 0-7");
props["outline"] = lvl.ToString();
h.Add(sheet, "row", pos, props);

static bool IsValidOutlineLevel(string s) => byte.TryParse(s, out var v) && v <= 7;

try { h.Add(sheet, "row", pos, props); }
catch (ArgumentException ex) when (ex.Message.Contains("Expected an integer 0-7"))
{ /* fix the outline value and retry or use 0 */ }

When it happens

Trigger: Add("/Sheet1","row",position,{["outline"]="8"}); or outlinelevel="-1"; group="abc" (fails byte.TryParse); group="9" (>7).

Common situations: Treating the outline level as a 1-based count instead of a 0-based level; copy-pasting a depth value from a tree structure that exceeds 8 nesting levels; passing a numeric string with a sign or decimal.

Related errors

• Invalid 'cols' value: '{colsStr}'. Expected a positive integ
• Invalid row index {rowIdx}. Valid row range is 1-1048576.
• Unrecognized cell parent path segment '{cellSegments[1]}'. E
• Invalid cell reference: '{cellRef}'
• --prop shift={shiftVal} not valid for add cell. Use 'right'

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