iOfficeAI/OfficeCLI · error · ArgumentException

Invalid {key}: '{value}'. Expected a percentage 0-100.

Error message

Invalid {key}: '{value}'. Expected a percentage 0-100.

What it means

Thrown when 'transparency', 'opacity', or 'alpha' is outside 0-100, or is NaN/Infinity. The computed OOXML alpha val is percent*1000 and must land in [0,100000]; out-of-range input produces a schema-invalid file PowerPoint/Excel refuse. 'transparency' is converted to opacity (100-x) after the range check, so 30% transparency is valid.

Source

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

                        var styleVal = ParseHelpers.SafeParseInt(value, "style");
                        if (styleVal < 1 || styleVal > 48)
                            throw new ArgumentException($"Invalid style: '{value}'. Valid range is 1-48.");
                        chartSpace.InsertBefore(new C.Style { Val = (byte)styleVal }, chart);
                    }
                    break;
                }

                // ---- #5 Fill transparency ----
                case "transparency" or "opacity" or "alpha":
                {
                    var plotArea2 = chart.GetFirstChild<C.PlotArea>();
                    if (plotArea2 == null) { unsupported.Add(key); break; }
                    var alphaPercent = ParseHelpers.SafeParseDouble(value, key);
                    // BUGFIX (NumericBoundaryScanTests): transparency/opacity/alpha
                    // are 0-100 percent. Out-of-range input drove the computed
                    // <a:alpha val> outside [0,100000] → schema-invalid file.
                    if (double.IsNaN(alphaPercent) || double.IsInfinity(alphaPercent) || alphaPercent < 0 || alphaPercent > 100)
                        throw new ArgumentException($"Invalid {key}: '{value}'. Expected a percentage 0-100.");
                    // If key is "transparency", convert to opacity (e.g. 30% transparency = 70% opacity)
                    if (key.Equals("transparency", StringComparison.OrdinalIgnoreCase))
                        alphaPercent = 100.0 - alphaPercent;
                    var alphaVal = (int)(alphaPercent * 1000); // OOXML uses 1/1000th percent
                    foreach (var ser in plotArea2.Descendants<OpenXmlCompositeElement>().Where(e => e.LocalName == "ser"))
                        ApplySeriesAlpha(ser, alphaVal);
                    break;
                }

                // ---- #6 Gradient fill ----
                // CONSISTENCY(gradient-fill-alias): accept `gradientFill=` as an
                // alias for `gradient=` so chart vocabulary matches shape/textbox
                // (ExcelHandler.Add.cs line 1931 / Set.cs line 727 use
                // BuildShapeGradientFill keyed on `gradientFill`).
                case "gradient" or "gradientfill":
                {
                    var plotArea2 = chart.GetFirstChild<C.PlotArea>();
                    if (plotArea2 == null) { unsupported.Add(key); break; }

View on GitHub (pinned to 1ced45e900)

Solutions

1. Express transparency/opacity/alpha as an integer/float percentage in [0,100].
2. If your source uses 0-1, multiply by 100 before passing.
3. Reject NaN/Infinity upstream (e.g. from a ratio with zero denominator).

Example fix

// before
SetChartProperties(part, new() { ["transparency"] = "0.3" }); // meant 30%
// after
SetChartProperties(part, new() { ["transparency"] = "30" });

static bool IsValidPercent(string v, out double pct) =>
    double.TryParse(v, NumberStyles.Float, CultureInfo.InvariantCulture, out pct)
    && !double.IsNaN(pct) && !double.IsInfinity(pct) && pct >= 0 && pct <= 100;

static bool IsPercent(double v) =>
    !double.IsNaN(v) && !double.IsInfinity(v) && v is >= 0 and <= 100;

try { SetChartProperties(part, props); }
catch (ArgumentException ex) when (ex.Message.Contains("Expected a percentage 0-100"))
{ /* rescale a 0-1 fraction to 0-100 and retry */ }

When it happens

Trigger: SetChartProperties with { ["transparency"] = "120" }, "-5", "NaN", or any value < 0 or > 100.

Common situations: Mixing up 0-1 fraction (0.3) with 0-100 percent (30); UI slider returning >100; infinity from a division-by-zero in alpha computation.

Related errors

• Unknown chart preset '{value}'. Available: {string.Join(", "
• Invalid labelPos '{value}' for pie chart: ST_DLblPosPie allo
• Invalid labelPos '{value}': expected one of ctr, inBase, inE
• axisMin={value} is invalid on a log-scaled axis: a logarithm
• Invalid majorUnit '{value}': must be a positive number (OOXM

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