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 colorFromNormalized(), each array value is passed to the channel's static fromNormalized(float $normalized). That parameter is a non-nullable float, so a null entry (or a wrong type under strict_types) raises a PHP TypeError, which the library catches and rethrows as this InvalidArgumentException. Note the distinction: an out-of-range float such as 1.5 throws 'Normalized color channel value must be between 0 to 1' from the channel itself; this particular message means a value was null or not a float.

Source

Thrown at src/Colors/Rgb/Colorspace.php:60

     * @see ColorspaceInterface::colorFromNormalized()
     *
     * @throws InvalidArgumentException
     */
    public static function colorFromNormalized(array $normalized): RgbColor
    {
        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): RgbColor

View on GitHub (pinned to 5598b9e397)

Solutions

1. Substitute defaults for null entries before calling: alpha defaults to 1.0
2. Normalize the array first: array_map(fn($v) => (float) ($v ?? 1.0), $values)
3. Validate that every entry is a float between 0 and 1 before the call

Example fix

// before
$color = Rgb\Colorspace::colorFromNormalized([$r, $g, $b, $alpha ?? null]); // TypeError wrapped

// after
$color = Rgb\Colorspace::colorFromNormalized([(float) $r, (float) $g, (float) $b, (float) ($alpha ?? 1.0)]);

$values = array_map(
    fn($v) => (float) ($v ?? 1.0), // substitute defaults for nulls
    $values
);
if (in_array(null, $values, true)) { /* still null somewhere */ }
$color = Rgb\Colorspace::colorFromNormalized($values);

function hasNoNullChannelValues(array $values): bool
{
    return !in_array(null, $values, true)
        && array_all($values, fn($v) => is_float($v) || is_int($v));
}

try {
    $color = Rgb\Colorspace::colorFromNormalized($values);
} catch (\Intervention\Image\Exceptions\InvalidArgumentException $e) {
    // a null/non-float entry slipped in; coerce and retry
    $safe = array_map(fn($v) => (float) ($v ?? 1.0), array_slice($values, 0, 4));
    $color = Rgb\Colorspace::colorFromNormalized($safe);
}

When it happens

Trigger: colorFromNormalized([0.5, 0.2, 0.8, null]) with a null alpha; arrays where array_map/array_combine left holes; values coming from json_decode() or nullable database columns passed unfiltered.

Common situations: Nullable columns (e.g. alpha or optional channel) flowing into color building; array_pad() to a longer length than data provided; strict_types making numeric strings like '0.5' unacceptable as float.

Related errors

• Number of color channels must be 3 or 4 for {class}
• Normalized color value must be in range 0 to 1
• Failed to import color {color_class} to {colorspace_class}
• Normalized color value must be in range 0 to 1
• Percentage value must be between -100 and 100

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