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

Oklch\Colorspace::colorFromNormalized() accepts exactly 3 normalized values (lightness, chroma, hue) or 4 (plus alpha), defaulting alpha to 1 when absent (src/Colors/Oklch/Colorspace.php:47-54). Any other array length throws InvalidArgumentException before values are examined.

Source

Thrown at src/Colors/Oklch/Colorspace.php:50

     */
    public static array $channels = [
        Lightness::class,
        Chroma::class,
        Hue::class,
        Alpha::class,
    ];

    /**
     * {@inheritdoc}
     *
     * @see ColorspaceInterface::colorFromNormalized()
     *
     * @throws InvalidArgumentException
     */
    public static function colorFromNormalized(array $normalized): OklchColor
    {
        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 [l, c, h] or [l, c, h, alpha] as normalized floats
2. Guard with count($values) === 3 || count($values) === 4 before the call
3. Use new Oklch\Color(l, c, h) when you hold real channel values

Example fix

// before
$color = Oklch\Colorspace::colorFromNormalized([0.5, 0.2]); // throws: must be 3 or 4

// after
$color = Oklch\Colorspace::colorFromNormalized([0.5, 0.2, 30]);
// or with alpha:
$color = Oklch\Colorspace::colorFromNormalized([0.5, 0.2, 30, 1.0]);

if (count($normalized) !== 3 && count($normalized) !== 4) {
    throw new \UnexpectedValueException('Expected [l, c, h(, alpha)] normalized values.');
}
$color = Oklch\Colorspace::colorFromNormalized($normalized);

function isOklchNormalizedArray(mixed $values): bool
{
    return is_array($values) && in_array(count($values), [3, 4], true);
}

When it happens

Trigger: Calling Oklch\Colorspace::colorFromNormalized() with 2 or 5+ entries or an empty array, e.g. after an array_map/array_filter step accidentally changed the array size.

Common situations: Dynamically built channel arrays where keys go missing or extra values are appended; code ported from RGB (3 channels) into OKLCH without adding hue, or from CMYK (4+alpha) without trimming.

Related errors

• Number of color channels must be 3 or 4 for {class}
• Unable to parse OKLCH color from input "{input}"
• Normalized color value must be in range 0 to 1
• Unable to import color {color_class} to {colorspace_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/810e61f80e1c9e5c. Report an issue: GitHub.