iOfficeAI/OfficeCLI · error · ArgumentException

Invalid color value: '{original}'. Alpha must be 0-1 (e.g. 0

Error message

Invalid color value: '{original}'. Alpha must be 0-1 (e.g. 0.5) or 0%-100%.

What it means

Thrown by ParseAlphaComponent when alpha is a bare decimal (no %) that does not parse or is outside the 0-1 range. Alpha as a fraction must be in [0,1]; values like 1.5 or -0.2 are rejected. If you want to express 50%, either write 0.5 or 50%.

Source

Thrown at src/officecli/Core/ParseHelpers.cs:186

            throw new ArgumentException($"Invalid color value: '{original}'. RGB components must be 0-255.");
        return (byte)n;
    }

    private static byte ParseAlphaComponent(string token, string original)
    {
        token = token.Trim();
        double a;
        if (token.EndsWith('%'))
        {
            if (!double.TryParse(token[..^1], NumberStyles.Float, CultureInfo.InvariantCulture, out var pct)
                || pct < 0 || pct > 100)
                throw new ArgumentException($"Invalid color value: '{original}'. Alpha percentage must be 0%-100%.");
            a = pct / 100.0;
        }
        else
        {
            if (!double.TryParse(token, NumberStyles.Float, CultureInfo.InvariantCulture, out a) || a < 0 || a > 1)
                throw new ArgumentException($"Invalid color value: '{original}'. Alpha must be 0-1 (e.g. 0.5) or 0%-100%.");
        }
        return (byte)Math.Round(a * 255.0);
    }

    private static double ParseHueDegrees(string token, string original)
    {
        token = token.Trim();
        // Strip an optional `deg` suffix (CSS allows it; other angle units
        // — turn/rad/grad — are out of scope for the input vocabulary we care
        // about and would just need their own multipliers if asked for).
        if (token.EndsWith("deg", StringComparison.OrdinalIgnoreCase))
            token = token[..^3].Trim();
        if (!double.TryParse(token, NumberStyles.Float, CultureInfo.InvariantCulture, out var h))
            throw new ArgumentException($"Invalid color value: '{original}'. Hue must be a number in degrees.");
        h %= 360;
        if (h < 0) h += 360;
        return h;
    }

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Express alpha as a fraction in [0,1] (e.g. 0.5).
  2. If your value is a percentage, append % (50%) instead of dividing nothing.
  3. Clamp the fraction: alpha = Math.Clamp(alpha, 0.0, 1.0).

Example fix

// before
var c = $"rgba(0,0,0,{opacity})"); // opacity == 1.5
ParseColor(c); // throws 287

// after
var c = $"rgba(0,0,0,{Math.Clamp(opacity,0.0,1.0)})");
ParseColor(c);
Defensive patterns

Strategy: validation

Validate before calling

var a = Math.Clamp(opacity, 0.0, 1.0);
// build: $"rgba(0,0,0,{a})"

Type guard

static bool IsValidAlphaFraction(string token)
    => double.TryParse(token, CultureInfo.InvariantCulture, out var v) && v >= 0 && v <= 1;

Try / catch

try { color = ParseColor(spec); }
catch (ArgumentException ex) when (ex.Message.Contains("Alpha must be 0-1"))
{ spec = "rgba(0,0,0,1)"; }

Prevention

When it happens

Trigger: Passing rgba(0,0,0,1.5), rgba(0,0,0,50) (mistaking the fraction field for a percentage), or rgba(0,0,0,-0.1).

Common situations: Treating the alpha slot as a 0-100 percentage by habit; opacity computed as a ratio that can exceed 1; passing a raw integer from a 0-255 alpha texture.

Related errors

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