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

Color channel value of {class} must be in range 0 to 1

Error message

Color channel value of {class} must be in range 0 to 1

What it means

InsertModifier (watermarks) validates its $transparency float to the closed interval 0..1, where 1 is fully opaque and 0 fully transparent. Values outside — most commonly percentages like 50 or 0.5*100 mistakes — throw InvalidArgumentException in the constructor.

Source

Thrown at src/Colors/AlphaChannel.php:17

<?php

declare(strict_types=1);

namespace Intervention\Image\Colors;

use Intervention\Image\Exceptions\InvalidArgumentException;

class AlphaChannel extends AbstractColorChannel
{
    /**
     * @throws InvalidArgumentException
     */
    final public function __construct(float $value = 1)
    {
        if ($value < 0 || $value > 1) {
            throw new InvalidArgumentException(
                'Color channel value of ' . static::class . ' must be in range 0 to 1',
            );
        }

        $this->value = (int) $this->validValueOrFail(intval(round($value * $this->max())));
    }

    /**
     * {@inheritdoc}
     *
     * @see ColorChannelInterface::fromNormalized()
     *
     * @throws InvalidArgumentException
     */
    public static function fromNormalized(float $normalized): self
    {
        return new static($normalized);
    }

View on GitHub (pinned to 5598b9e397)

Solutions

1. Pass a fraction: transparency: 0.5 for 50% opacity.
2. Convert percent input: $transparency = $percent / 100 before insert().
3. Clamp when the source range is unknown: min(1, max(0, $value)).

Example fix

// before
$image->insert($watermark, transparency: 50); // throws, out of 0..1

// after
$image->insert($watermark, transparency: 50 / 100); // 0.5

$transparency = min(1.0, max(0.0, (float) $transparency));
$image->insert($watermark, transparency: $transparency);

When it happens

Trigger: $image->insert($watermark, offset-x: 0, offset-y: 0, transparency: 50); passing a 0-100 opacity value unchanged; converting '50%' opacity to 50 instead of 0.5.

Common situations: UI opacity sliders reporting 0-100; API docs elsewhere expressing transparency as percent; copy-pasting from libraries whose alpha is 0-127 (GD) or 0-255.

Related errors

• Failed to apply {class}, unable to set transparency of water
• Failed to build watermark image
• Failed to apply {class}, unable to insert watermark image
• Failed to invert color
• Color channel {class} value must be in range {min} to {max}

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