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

While mapping normalized values onto OKLCH channels, a value that is not a float (typically null) reached $channel::fromNormalized(); under strict types this raises a TypeError, which colorFromNormalized() rethrows as this InvalidArgumentException (src/Colors/Oklch/Colorspace.php:56-69). The null|float array type lets null pass the count check and fail only at channel construction.

Source

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

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

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

View on GitHub (pinned to 5598b9e397)

Solutions

1. Replace null entries with defaults before calling: array_map(fn($v) => $v ?? 0.0, $values)
2. Assert each entry is a float in 0..1 beforehand
3. Fix the upstream code that yields null for a channel

Example fix

// before
$color = Oklch\Colorspace::colorFromNormalized([$l, $c, $maybeNullHue]); // null -> this error

// after
$values = array_map(fn(?float $v): float => $v ?? 0.0, [$l, $c, $maybeNullHue]);
$color = Oklch\Colorspace::colorFromNormalized($values);

$normalized = array_map(fn(?float $v): float => $v ?? 0.0, $normalized);
foreach ($normalized as $v) {
    if (!is_float($v) || $v < 0.0 || $v > 1.0) {
        // repair or reject before colorFromNormalized()
    }
}

function isNormalizedFloatList(array $values): bool
{
    foreach ($values as $v) {
        if (!is_float($v) || $v < 0.0 || $v > 1.0) { return false; }
    }
    return true;
}

When it happens

Trigger: Calling Oklch\Colorspace::colorFromNormalized([0.5, null, 30]) or with string entries like ['0.5', '0.2', '30']; nulls usually originate from nullable config values or computations whose result was null.

Common situations: Channel arrays assembled from user settings or database rows with nullable fields; array_map callbacks that can return null.

Related errors

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