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 OKLAB channels, $channel::fromNormalized() was called with something that is not a float (usually null), which under strict types raises a TypeError that colorFromNormalized() converts into this InvalidArgumentException (src/Colors/Oklab/Colorspace.php:51-64). The array entries are typed null|float, so a null slips past the count check and only fails when handed to the channel.

Source

Thrown at src/Colors/Oklab/Colorspace.php:56

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

View on GitHub (pinned to 5598b9e397)

Solutions

1. Filter or default null entries before calling: $normalized = array_map(fn($v) => $v ?? 0.0, $normalized)
2. Validate every entry with is_float() and range 0..1 before the call
3. Fix the upstream computation that produced null for a channel

Example fix

// before
$color = Oklab\Colorspace::colorFromNormalized([$l, $maybeNull, $b]); // null -> TypeError -> this error

// after
$normalized = array_map(fn(?float $v): float => $v ?? 0.0, [$l, $maybeNull, $b]);
$color = Oklab\Colorspace::colorFromNormalized($normalized);

$normalized = array_map(
    fn(?float $v): float => $v ?? 0.0,
    $normalized,
);
$invalid = array_filter($normalized, fn($v) => !is_float($v) || $v < 0.0 || $v > 1.0);
if ($invalid !== []) {
    // fix upstream data before calling 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 Oklab\Colorspace::colorFromNormalized([0.5, null, 0.3]) or with a string entry like ['0.5', 0.1, 0.2]; nulls typically come from lookups or computations that returned null (e.g. optional config values, failed calculations) and were put into the array unfiltered.

Common situations: Building normalized arrays from user config or database rows where a field is nullable; using array_map with a callback that can return null.

Related errors

• Normalized color value must be in range 0 to 1
• Unable to parse OKLAB 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/b56a4ee7805002ee. Report an issue: GitHub.