{"record":{"id":"30a073e8fbc6d51f","repo":"iOfficeAI/OfficeCLI","slug":"col-property-is-required-for-colbreak","errorCode":null,"errorMessage":"'col' property is required for colbreak","messagePattern":"'col' property is required for colbreak","errorType":"validation","errorClass":"System.ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Add.Cells.cs","lineNumber":1375,"sourceCode":"        SaveWorksheet(rbWorksheet);\n\n        var rbIdx = rowBreaks.Elements<Break>().ToList()\n            .FindIndex(b => b.Id?.Value == rbRowIdx) + 1;\n        return $\"/{rbSheetName}/rowbreak[{rbIdx}]\";\n    }\n\n    private string AddColBreak(string parentPath, string type, InsertPosition? position, Dictionary<string, string> properties)\n    {\n        var index = position?.Index;\n        var cbSegments = parentPath.TrimStart('/').Split('/', 2);\n        var cbSheetName = cbSegments[0];\n        var cbWorksheet = FindWorksheet(cbSheetName)\n            ?? throw new ArgumentException($\"Sheet not found: {cbSheetName}\");\n        var cbWs = GetSheet(cbWorksheet);\n\n        var cbColStr = properties.GetValueOrDefault(\"col\") ?? properties.GetValueOrDefault(\"column\")\n            ?? properties.GetValueOrDefault(\"index\")\n            ?? throw new ArgumentException(\"'col' property is required for colbreak\");\n        // Accept both numeric index (e.g. \"3\") and column letter (e.g. \"C\")\n        var cbColIdx = uint.TryParse(cbColStr, out var cbNumVal)\n            ? cbNumVal\n            : (uint)ColumnNameToIndex(cbColStr.ToUpperInvariant());\n        // Same schema Min/Max guard as rowbreak: 0 / beyond-XFD ids write\n        // invalid OOXML that only surfaces at validate/open time.\n        if (cbColIdx < 1 || cbColIdx > 16384)\n            throw new ArgumentException(\n                $\"Invalid 'col' value: '{cbColStr}'. Column breaks must be between 1 and 16384 (A-XFD).\");\n\n        var colBreaks = cbWs.GetFirstChild<ColumnBreaks>();\n        if (colBreaks == null)\n        {\n            colBreaks = new ColumnBreaks();\n            cbWs.AppendChild(colBreaks);\n        }\n        // Optional restricted row span (min/max) — mirrors the Set path.\n        var cbBreak = new Break { Id = cbColIdx, Max = 1048575u, ManualPageBreak = true };","sourceCodeStart":1357,"sourceCodeEnd":1393,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Add.Cells.cs#L1357-L1393","documentation":"Thrown by AddColBreak when none of the col, column, or index properties are present in the properties dictionary. The lookup chains GetValueOrDefault for all three aliases and throws if all return null. A column break requires a target column, so omitting it is unrecoverable.","triggerScenarios":"Add type=colbreak with a properties dictionary lacking col/column/index (e.g. only min/max, or empty). If col is present but empty, ColumnNameToIndex later throws rather than this guard. This throw specifically requires all three keys absent.","commonSituations":"User copies a rowbreak command and forgets to change row to col. Conditional property construction where the col branch is skipped. Assuming the position's Index supplies the column (it does not for colbreak).","solutions":["Add a col property: properties[\"col\"]=\"C\" (letter) or \"3\" (numeric).","column and index are accepted aliases.","If you meant a row break, use type=rowbreak with row= instead."],"exampleFix":"// before\nhandler.Add(\"/Sheet1\", \"colbreak\", null, new() { [\"min\"] = \"1\" });\n\n// after\nhandler.Add(\"/Sheet1\", \"colbreak\", null, new() { [\"col\"] = \"C\", [\"min\"] = \"1\" });","handlingStrategy":"validation","validationCode":"if (!props.ContainsKey(\"col\") && !props.ContainsKey(\"column\") && !props.ContainsKey(\"index\"))\n    throw new InvalidOperationException(\"colbreak requires 'col', 'column', or 'index'\");\nhandler.Add(\"/Sheet1\", \"colbreak\", null, props);","typeGuard":"static bool HasColbreakTarget(IReadOnlyDictionary<string,string> p)\n    => p.ContainsKey(\"col\") || p.ContainsKey(\"column\") || p.ContainsKey(\"index\");","tryCatchPattern":null,"preventionTips":["Always set col= explicitly when constructing a colbreak command.","Use a builder that requires the column parameter at compile time.","Distinguish colbreak (col=) from rowbreak (row=) when copying commands."],"tags":["excel","ooxml","colbreak","missing-property","argument"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}