iOfficeAI/OfficeCLI · error · ArgumentException

Invalid color value: '{original}'. RGB components must be 0-

Error message

Invalid color value: '{original}'. RGB components must be 0-255.

What it means

Thrown by ParseRgbComponent when an RGB component is an integer-style token (no %) that fails to parse or is outside 0-255. This is the 0-255 branch; percentage components are handled separately. Each channel must be a whole number in the inclusive 0-255 range.

Source

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

                : (byte?)null;
            return ($"{r:X2}{g:X2}{b:X2}", a);
        }

        return null;
    }

    private static byte ParseRgbComponent(string token, string original)
    {
        token = token.Trim();
        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}'. RGB percentage components must be 0%-100%.");
            return (byte)Math.Round(pct / 100.0 * 255.0);
        }
        if (!int.TryParse(token, NumberStyles.Integer, CultureInfo.InvariantCulture, out var n) || n < 0 || n > 255)
            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%.");

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Clamp each channel to [0,255] and keep it integer.
  2. If you have a fractional value, use percentage form (0%-100%) instead.
  3. Round float channels before formatting: (byte)Math.Round(f).

Example fix

// before
var c = $"rgb({r},{g},{b}")); // r == 300
ParseColor(c); // throws 285

// after
byte Clamp(double v) => (byte)Math.Round(Math.Clamp(v,0,255));
var c = $"rgb({Clamp(r)},{Clamp(g)},{Clamp(b)})");
ParseColor(c);
Defensive patterns

Strategy: validation

Validate before calling

static byte ClampByte(double v) => (byte)Math.Clamp(Math.Round(v),0,255);
// build: $"rgb({ClampByte(r)},{ClampByte(g)},{ClampByte(b)})"

Type guard

static bool IsValidRgbByte(string token)
    => int.TryParse(token, CultureInfo.InvariantCulture, out var n) && n >= 0 && n <= 255;

Try / catch

try { color = ParseColor(spec); }
catch (ArgumentException ex) when (ex.Message.Contains("0-255"))
{ color = Color.Black; }

Prevention

When it happens

Trigger: Passing rgb(300,0,0), rgb(-10,0,0), or rgb(x,0,0). Also triggered by fractional 0-255 values like rgb(128.5,0,0) since this branch uses int.TryParse.

Common situations: Summing color channels and overflowing 255; using a color from a library that emits floats; negative values from a subtractive blend.

Related errors

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