iOfficeAI/OfficeCLI · warning · ArgumentException

Invalid color transform '{token}': raw value {raw} out of ra

Error message

Invalid color transform '{token}': raw value {raw} out of range {minRaw}-{maxRaw}.

What it means

In eqForm (token had '='), the parsed raw integer fell outside the OOXML range for that transform family. For fixed-percentage transforms (shade/tint/alpha) the raw range is 0..100000; for the signed Mod/Off family (lumMod/lumOff/satMod/satOff/hueMod/hueOff) it is -1000000..1000000. The bounds reflect the OOXML ST_PositiveFixedPercentage vs ST_Percentage schema types.

Source

Thrown at src/officecli/Core/DrawingColorBuilder.cs:141

            //                           negatives forbidden.
            //   lumMod / lumOff / satMod / satOff / hueMod / hueOff
            //                         → ST_Percentage: SIGNED and may exceed 100%
            //                           (e.g. satMod200% to over-saturate, or
            //                           satOff-10% to desaturate). Rejecting
            //                           negatives wrongly aborted replay of the
            //                           round-trip form Get emits for these
            //                           (satOff val="-10000" → "satOff-10").
            // Only the fixed-percentage family stays clamped 0..100.
            bool fixedPct = name.ToLowerInvariant() is "shade" or "tint" or "alpha";
            int maxPct = fixedPct ? 100 : 1000;       // 1000% headroom for ST_Percentage
            int minPct = fixedPct ? 0 : -1000;        // signed for the Mod/Off family
            int maxRaw = fixedPct ? 100000 : 1000000;
            int minRaw = fixedPct ? 0 : -1000000;
            int pct;
            if (eqForm)
            {
                if (raw < minRaw || raw > maxRaw)
                    throw new ArgumentException(
                        $"Invalid color transform '{token}': raw value {raw} out of range {minRaw}-{maxRaw}.");
                // OOXML raw units are 1/1000 of a percent. Integer division
                // truncates values whose magnitude is 1..999 to 0 (lumMod=75 raw
                // → 0 instead of 7.5%). Reject sub-1000 magnitudes so callers
                // can't silently get a no-op; the percentage form covers that range.
                if (raw != 0 && Math.Abs(raw) < 1000)
                    throw new ArgumentException(
                        $"Invalid color transform '{token}': raw value {raw} below 1000 truncates to 0%; use percentage form '{name}{raw / 1000}' or raw magnitude >= 1000.");
                pct = raw / 1000;
            }
            else
            {
                if (raw < minPct || raw > maxPct)
                    throw new ArgumentException(
                        $"Invalid color transform '{token}': percentage {raw} out of range {minPct}-{maxPct}.");
                pct = raw;
            }
            // Canonicalize: lumMod → lumMod (lowercase first letter? OOXML uses

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Use the percentage form instead of raw eqForm for human-scale values: 'shade85' rather than 'shade=85000'.
  2. Keep fixed-percentage transforms (shade/tint/alpha) within 0..100 (raw 0..100000).
  3. Keep Mod/Off transforms within -1000..1000 percent (raw -1000000..1000000).

Example fix

// before — raw eqForm out of range
fill="red shade=200000"

// after — percentage form, clamped to valid range
fill="red shade100"
Defensive patterns

Strategy: validation

Validate before calling

static (int min, int max) RawRange(string name)
{
    bool fixedPct = name.ToLowerInvariant() is "shade" or "tint" or "alpha";
    return fixedPct ? (0, 100000) : (-1000000, 1000000);
}
// Validate before building: ensure raw eqForm value lies within RawRange(name).

Try / catch

try { DrawingColorBuilder.Build(color); }
catch (ArgumentException ex) when (ex.Message.Contains("out of range", StringComparison.Ordinal))
{ errors.Add(ex.Message); }

Prevention

When it happens

Trigger: An eqForm value beyond the schema ceiling/floor: 'shade=200000' (fixed-pct max 100000), 'alpha=150000', 'lumMod=5000000', or a negative fixed-pct like 'shade=-10000'. minRaw/maxRaw in the message state the exact allowed range.

Common situations: Confusing raw OOXML units (1/1000 of a percent) with plain percentages and entering a too-large number; trying to over-apply a fixed-percentage transform past 100%; using a negative where the schema forbids it.

Related errors

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