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

Hsv\Colorspace::colorFromNormalized() constructs an Hsv\Color from an array of normalized values and requires exactly 3 entries (hue, saturation, value) or 4 entries (plus alpha, defaulted to 1 when omitted). Any other element count throws this InvalidArgumentException before values are examined.

Source

Thrown at src/Colors/Hsv/Colorspace.php:46

     */
    public static array $channels = [
        Channels\Hue::class,
        Channels\Saturation::class,
        Channels\Value::class,
        Channels\Alpha::class,
    ];

    /**
     * {@inheritdoc}
     *
     * @see ColorspaceInterface::colorFromNormalized()
     *
     * @throws InvalidArgumentException
     */
    public static function colorFromNormalized(array $normalized): HsvColor
    {
        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 [hue, saturation, value] or [hue, saturation, value, alpha], all 0.0-1.0
2. array_slice($values, 0, 4) or unset() extra keys before the call
3. Validate count at the input boundary and reject/fix malformed payloads early
4. Use Hsv\Color::create($h, $s, $v, $a) when values are already in 0-360 / 0-100 units

Example fix

// before
$color = Hsv\Colorspace::colorFromNormalized([$h, $s, $v, $a, 'label']);

// after
$color = Hsv\Colorspace::colorFromNormalized([$h, $s, $v, $a]);

if (!in_array(count($normalized), [3, 4], true)) {
    throw new InvalidArgumentException('Expected 3 or 4 normalized channels, got ' . count($normalized));
}
$color = Hsv\Colorspace::colorFromNormalized($normalized);

function isHsvNormalizedArray(array $values): bool
{
    return in_array(count($values), [3, 4], true)
        && !in_array(null, $values, true);
}

When it happens

Trigger: Hsv\Colorspace::colorFromNormalized([0.3, 0.6]) or an array with 5+ entries; arrays assembled by exploding user strings like '0.3 0.6 0.5 1.0 extra'; passing an associative array that carries additional metadata keys.

Common situations: Color-picker or API payloads where an extra field (name, id) rides along in the same array; loop code appending units or labels; off-by-one slicing of channel arrays.

Related errors

• Number of color channels must be 3 or 4 for {class}
• Normalized color value must be in range 0 to 1
• Normalized color channel value must be between 0 to 1
• Normalized color value must be in range 0 to 1
• Unable to parse HSV color from input "{input}"

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