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

Normalized color value must be in range 0 to 1

Error message

Normalized color value must be in range 0 to 1

What it means

In Hsv\Colorspace::colorFromNormalized() each array entry is passed to a channel factory whose parameter is typed float. A null entry therefore raises a TypeError, which is caught and converted to this InvalidArgumentException reading 'Normalized color value must be in range 0 to 1'. The message is misleading for this code path: the real trigger is a null (or non-float) element, not an out-of-range float.

Source

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

     * @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,
        ));
    }

    /**
     * {@inheritdoc}
     *
     * @see ColorspaceInterface::importColor()
     *
     * @throws InvalidArgumentException
     * @throws ColorException
     */

View on GitHub (pinned to 5598b9e397)

Solutions

1. Substitute defaults first: $values = array_map(fn ($v) => floatval($v ?? 0.0), $values)
2. If null means default alpha, pass a 3-element array so alpha defaults to 1.0
3. Filter nulls out only when you know which channel they belong to (order matters)
4. Enforce non-null float types in form/API validation before reaching image code

Example fix

// before
$color = Hsv\Colorspace::colorFromNormalized($payload); // [0.3, null, 0.5]

// after
$payload = array_map(fn ($v) => floatval($v ?? 0.0), $payload);
$color = Hsv\Colorspace::colorFromNormalized($payload);

$normalized = array_map(fn ($v) => floatval($v ?? 0.0), $normalized);
if (in_array(null, $normalized, true)) {
    throw new InvalidArgumentException('null channel value');
}

function hasNoNullChannels(array $values): bool
{
    return !in_array(null, $values, true);
}

When it happens

Trigger: Hsv\Colorspace::colorFromNormalized([0.3, null, 0.5]) - arrays sourced from nullable DB columns, optional JSON fields, or array_map over data containing nulls; also string values under strict_types=1.

Common situations: Nullable 'alpha' or 'saturation' columns where NULL means 'default'; API payloads with optional channel keys; applying defaults after the conversion call instead of before.

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
• Number of color channels must be 3 or 4 for {class}
• Unable to parse HSV color from input "{input}"

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