iOfficeAI/OfficeCLI · error · ArgumentException

Invalid gapWidth: '{value}'. Expected integer 0-500.

Error message

Invalid gapWidth: '{value}'. Expected integer 0-500.

What it means

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.

Source

Thrown at src/officecli/Core/Chart/ChartHelper.Setter.cs:1609

                            // Insert ln before effectLst per DrawingML schema order
                            var effLst = spPr.GetFirstChild<Drawing.EffectList>();
                            if (effLst != null) spPr.InsertBefore(outline, effLst);
                            else spPr.AppendChild(outline);
                        }
                    }
                    break;
                }

                case "gapwidth" or "gap":
                {
                    var plotArea2 = chart.GetFirstChild<C.PlotArea>();
                    if (plotArea2 == null) { unsupported.Add(key); break; }
                    if (!int.TryParse(value, out var gw)) throw new ArgumentException($"Invalid gapWidth: '{value}'. Expected integer (0-500).");
                    // BUGFIX (NumericBoundaryScanTests): enforce the stated 0-500
                    // range. CT_GapAmount is ST_GapAmountUShort (0-500); out-of-range
                    // (incl. negatives wrapping via (ushort) cast) produced a
                    // schema-invalid c:gapWidth PowerPoint refuses to open.
                    if (gw < 0 || gw > 500) throw new ArgumentException($"Invalid gapWidth: '{value}'. Expected integer 0-500.");
                    bool gapUpdated = false;
                    foreach (var gapEl in plotArea2.Descendants<C.GapWidth>())
                    {
                        gapEl.Val = (ushort)gw;
                        gapUpdated = true;
                    }
                    if (!gapUpdated)
                    {
                        // No existing GapWidth — create one per bar/column chart element.
                        // This occurs when RebuildComboChart (applied via deferred
                        // comboTypes= prop) replaces the original barChart (which had
                        // a GapWidth seeded by BuildBarChart) with freshly constructed
                        // barChart elements that have no GapWidth child. The `foreach
                        // Descendants` above then finds nothing and the gapwidth round-
                        // trips as lost. Mirror the `overlap` upsert pattern.
                        var barEls = plotArea2.Elements<OpenXmlCompositeElement>()
                            .Where(e => e.LocalName == "barChart" || e.LocalName == "bar3DChart")
                            .ToList();

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Clamp gapWidth to 0-500 before passing.
  2. Distinguish gap (0-500) from overlap (-100..100) in your config schema.
  3. Reject the value upstream rather than relying on the throw.

Example fix

// before
SetChartProperties(part, new() { ["gapWidth"] = "-10" });
// after
SetChartProperties(part, new() { ["gapWidth"] = Math.Clamp(gap, 0, 500).ToString() });
Defensive patterns

Strategy: validation

Validate before calling

static bool IsValidGapWidth(string v, out int gw) =>
    int.TryParse(v?.Trim(), NumberStyles.Integer, CultureInfo.InvariantCulture, out gw)
    && gw >= 0 && gw <= 500;

Type guard

static bool IsLegalGapWidth(int gw) => gw is >= 0 and <= 500;

Try / catch

try { SetChartProperties(part, props); }
catch (ArgumentException ex) when (ex.Message.Contains("gapWidth") && ex.Message.Contains("0-500"))
{ /* clamp to 0-500 and retry */ }

Prevention

When it happens

Trigger: SetChartProperties with { ["gapWidth"] = "-10" }, "600", or "9999".

Common situations: Negative gap from an overlap-vs-gap sign confusion; unbounded UI slider; computed gap from data that exceeds the schema ceiling.

Related errors

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