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

Inside Hsl\Colorspace::colorFromNormalized() each normalized value is passed to the channel factory FloatColorChannel/IntColorChannel::fromNormalized(), which declares a float parameter. Passing null therefore raises a PHP TypeError, which the colorspace catches and converts to this InvalidArgumentException stating 'Normalized color value must be in range 0 to 1'. Despite the message, the actual cause for this specific error is a null (or non-float) entry - out-of-range floats throw a different exception from the channel itself.

Source

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

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

    /**
     * {@inheritdoc}
     *
     * @see ColorspaceInterface::importColor()
     *
     * @throws ColorException
     */
    public function importColor(ColorInterface $color): HslColor

View on GitHub (pinned to 5598b9e397)

Solutions

1. Replace nulls with defaults before calling: $values = array_map(fn ($v) => $v ?? 0.0, $values)
2. Coerce types: $values = array_map(fn ($v) => floatval($v ?? 0.0), $values)
3. If null means 'use default alpha', omit the 4th entry entirely (3-entry array gets alpha 1.0)
4. Reject nulls at the data boundary (form request / API validation) instead of inside image code

Example fix

// before
$color = Hsl\Colorspace::colorFromNormalized($row); // $row = [0.5, null, 0.5]

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

$normalized = array_map(
    fn ($v) => is_finite((float) $v) ? floatval($v) : 0.0,
    array_map(fn ($v) => $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: Hsl\Colorspace::colorFromNormalized([0.5, null, 0.5]) - arrays built from nullable database columns, optional API fields, or array_map over data containing nulls. Also any non-float type the channel factory cannot accept (e.g. strings under strict_types).

Common situations: Colors assembled from Eloquent/Doctrine records where saturation or alpha is NULL when unspecified; JSON payloads with optional channel keys; defaults applied after the 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
• 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/4aca64c205b60428. Report an issue: GitHub.