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

Hsl\Colorspace::colorFromNormalized() builds an Hsl\Color from an array of normalized (0.0-1.0) channel values and requires exactly 3 entries (hue, saturation, luminance) or 4 entries (plus alpha; alpha defaults to 1 when omitted). Any other count throws this InvalidArgumentException before any value is inspected.

Source

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

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

    /**
     * {@inheritdoc}
     *
     * @see ColorspaceInterface::colorFromNormalized()
     *
     * @throws InvalidArgumentException
     */
    public static function colorFromNormalized(array $normalized): HslColor
    {
        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, luminance] or [hue, saturation, luminance, alpha] with values in 0.0-1.0
2. Slice/array_slice or unset extra keys before the call
3. Validate the count at the boundary: if (!in_array(count($data), [3, 4])) reject the payload early
4. Build via Hsl\Color::create($h, $s, $l) when your values are already in 0-360 / 0-100 units

Example fix

// before
$color = Hsl\Colorspace::colorFromNormalized([$h, $s, $l, $a, $extra]);

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

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

function isHslNormalizedArray(array $values): bool
{
    return in_array(count($values), [3, 4], true)
        && array_reduce($values, fn ($ok, $v) => $ok && is_float($v), true);
}

When it happens

Trigger: Hsl\Colorspace::colorFromNormalized([0.5, 0.5]) (2 values); colorFromNormalized([0.1, 0.2, 0.3, 0.4, 0.5]) (5 values); arrays built by exploding a user string like 'hsl 0.1 0.2 0.3 0.4 0.5' on whitespace; forgetting that alpha belongs in the same array rather than a separate argument.

Common situations: Mapping generic 3/4-channel color data (e.g. from a color picker widget or API payload) that occasionally carries extra keys; appending a units suffix as an extra element; associative arrays with unexpected extra entries passed straight through.

Related errors

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

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