{"record":{"id":"1c6aac90cb82ff99","repo":"iOfficeAI/OfficeCLI","slug":"invalid-gapwidth-value-expected-integer-0-50","errorCode":null,"errorMessage":"Invalid gapWidth: '{value}'. Expected integer 0-500.","messagePattern":"Invalid gapWidth: '(.+?)'\\. Expected integer 0-500\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Core/Chart/ChartHelper.Setter.cs","lineNumber":1609,"sourceCode":"                            // Insert ln before effectLst per DrawingML schema order\n                            var effLst = spPr.GetFirstChild<Drawing.EffectList>();\n                            if (effLst != null) spPr.InsertBefore(outline, effLst);\n                            else spPr.AppendChild(outline);\n                        }\n                    }\n                    break;\n                }\n\n                case \"gapwidth\" or \"gap\":\n                {\n                    var plotArea2 = chart.GetFirstChild<C.PlotArea>();\n                    if (plotArea2 == null) { unsupported.Add(key); break; }\n                    if (!int.TryParse(value, out var gw)) throw new ArgumentException($\"Invalid gapWidth: '{value}'. Expected integer (0-500).\");\n                    // BUGFIX (NumericBoundaryScanTests): enforce the stated 0-500\n                    // range. CT_GapAmount is ST_GapAmountUShort (0-500); out-of-range\n                    // (incl. negatives wrapping via (ushort) cast) produced a\n                    // schema-invalid c:gapWidth PowerPoint refuses to open.\n                    if (gw < 0 || gw > 500) throw new ArgumentException($\"Invalid gapWidth: '{value}'. Expected integer 0-500.\");\n                    bool gapUpdated = false;\n                    foreach (var gapEl in plotArea2.Descendants<C.GapWidth>())\n                    {\n                        gapEl.Val = (ushort)gw;\n                        gapUpdated = true;\n                    }\n                    if (!gapUpdated)\n                    {\n                        // No existing GapWidth — create one per bar/column chart element.\n                        // This occurs when RebuildComboChart (applied via deferred\n                        // comboTypes= prop) replaces the original barChart (which had\n                        // a GapWidth seeded by BuildBarChart) with freshly constructed\n                        // barChart elements that have no GapWidth child. The `foreach\n                        // Descendants` above then finds nothing and the gapwidth round-\n                        // trips as lost. Mirror the `overlap` upsert pattern.\n                        var barEls = plotArea2.Elements<OpenXmlCompositeElement>()\n                            .Where(e => e.LocalName == \"barChart\" || e.LocalName == \"bar3DChart\")\n                            .ToList();","sourceCodeStart":1591,"sourceCodeEnd":1627,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Core/Chart/ChartHelper.Setter.cs#L1591-L1627","documentation":"Thrown when 'gapWidth'/'gap' parses as an integer but is outside 0-500 (OOXML ST_GapAmountUShort). This is the range-check path distinct from the parse-failure throw (error 152). Without it, an out-of-range value (including negatives that wrap via the (ushort) cast) produced a schema-invalid c:gapWidth that PowerPoint refuses to open. Atomic — validated before mutating gap elements.","triggerScenarios":"SetChartProperties with { [\"gapWidth\"] = \"-10\" }, \"600\", or \"9999\".","commonSituations":"Negative gap from an overlap-vs-gap sign confusion; unbounded UI slider; computed gap from data that exceeds the schema ceiling.","solutions":["Clamp gapWidth to 0-500 before passing.","Distinguish gap (0-500) from overlap (-100..100) in your config schema.","Reject the value upstream rather than relying on the throw."],"exampleFix":"// before\nSetChartProperties(part, new() { [\"gapWidth\"] = \"-10\" });\n// after\nSetChartProperties(part, new() { [\"gapWidth\"] = Math.Clamp(gap, 0, 500).ToString() });","handlingStrategy":"validation","validationCode":"static bool IsValidGapWidth(string v, out int gw) =>\n    int.TryParse(v?.Trim(), NumberStyles.Integer, CultureInfo.InvariantCulture, out gw)\n    && gw >= 0 && gw <= 500;","typeGuard":"static bool IsLegalGapWidth(int gw) => gw is >= 0 and <= 500;","tryCatchPattern":"try { SetChartProperties(part, props); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"gapWidth\") && ex.Message.Contains(\"0-500\"))\n{ /* clamp to 0-500 and retry */ }","preventionTips":["Distinguish gapWidth (0-500) from overlap (-100..100) in your schema.","Clamp negative or oversized values before sending.","Treat a negative gap as a probable overlap/flip in sign convention."],"tags":["ooxml","chart","input-validation","bar-chart","csharp"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}