Intervention/image · error · Intervention\Image\Exceptions\InvalidArgumentException

Number of color channels must be 3 or 4 for {class}

Error message

Number of color channels must be 3 or 4 for {class}

What it means

Rgb\Colorspace::colorFromNormalized() builds an RGB color from an array of normalized (0..1) channel values and requires exactly 3 (r,g,b) or 4 (r,g,b,alpha) entries; a 3-entry array automatically gets alpha=1 appended. Any other count throws InvalidArgumentException naming the colorspace class.

Source

Thrown at src/Colors/Rgb/Colorspace.php:49

     */
    public static array $channels = [
        Channels\Red::class,
        Channels\Green::class,
        Channels\Blue::class,
        Channels\Alpha::class,
    ];

    /**
     * {@inheritdoc}
     *
     * @see ColorspaceInterface::colorFromNormalized()
     *
     * @throws InvalidArgumentException
     */
    public static function colorFromNormalized(array $normalized): RgbColor
    {
        if (!in_array(count($normalized), [3, 4])) {
            throw new InvalidArgumentException('Number of color channels must be 3 or 4 for ' . static::class);
        }

        // add alpha value if missing
        $normalized = count($normalized) === 3 ? array_pad($normalized, 4, 1) : $normalized;

        return new Color(...array_map(
            function (string $channel, null|float $normalized) {
                try {
                    return $channel::fromNormalized($normalized);
                } catch (TypeError $e) {
                    throw new InvalidArgumentException(
                        'Normalized color value must be in range 0 to 1',
                        previous: $e,
                    );
                }
            },
            self::$channels,
            $normalized,

View on GitHub (pinned to 5598b9e397)

Solutions

1. Pass exactly 3 or 4 normalized floats in r,g,b(,alpha) order
2. Build the array from an already-converted color: array_map(fn($c) => $c->normalized(), $color->toColorspace(Rgb\Colorspace::class)->channels())
3. Prefer the higher-level API: $color->toColorspace(Rgb\Colorspace::class) or Colorspace->importColor($color) instead of assembling arrays manually
4. In generic code, count-check the array and slice/pad to 4 before calling

Example fix

// before
$color = \Intervention\Image\Colors\Rgb\Colorspace::colorFromNormalized([0.5, 0.2]);

// after
$color = \Intervention\Image\Colors\Rgb\Colorspace::colorFromNormalized([0.5, 0.2, 0.8]);

$values = array_map(fn($v) => (float) $v, $values);
if (!in_array(count($values), [3, 4], true)) {
    throw new \InvalidArgumentException('Expected 3 or 4 normalized channel values');
}
$color = \Intervention\Image\Colors\Rgb\Colorspace::colorFromNormalized($values);

function isNormalizedRgbArray(array $values): bool
{
    return in_array(count($values), [3, 4], true)
        && array_all($values, fn($v) => is_float($v) && $v >= 0.0 && $v <= 1.0);
}

try {
    $color = Rgb\Colorspace::colorFromNormalized($values);
} catch (\Intervention\Image\Exceptions\InvalidArgumentException $e) {
    // rebuild from a safe default and log the bad payload
    $color = Rgb\Colorspace::colorFromNormalized([0.0, 0.0, 0.0, 1.0]);
}

When it happens

Trigger: colorFromNormalized([0.5, 0.2]) (two values), colorFromNormalized([0.1, 0.2, 0.3, 0.5, 0.1]) (five values), or forwarding a foreign colorspace's channels() array (e.g. CMYK has 4+alpha=5 channels) to the RGB colorspace.

Common situations: Writing generic colorspace code that copies channel arrays between colorspaces with different channel counts; building normalized arrays in loops with an off-by-one; unpacking database or CSV payloads where a column is missing or extra.

Related errors

• Normalized color value must be in range 0 to 1
• Failed to import color {color_class} to {colorspace_class}
• Percentage value must be between -100 and 100
• Failed to import color {colorClass} to {class}
• Failed to import color {color_class} to {colorspace_class}

AI-assisted analysis of Intervention/image@5598b9e397 (2026-08-23). Data as JSON: /api/errors/8ecd47b94b96722f. Report an issue: GitHub.