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

Failed to import color {colorClass} to {class}

Error message

Failed to import color {colorClass} to {class}

What it means

When Hsl\Colorspace::importRgbColor() converts an RgbColor to HSL, it computes hue (0-360), saturation and luminance (0-100) and constructs an Hsl\Color with the source alpha. If that constructor rejects a value (InvalidArgumentException from a channel), it is re-thrown as this ColorException with the constructor error attached as previous. With valid RgbColor input the math stays in range, so in practice the alpha channel of the source is the usual culprit.

Source

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

        $hue = match (true) {
            ($delta === 0.0) => 0,
            ($max === $r) => 60 * fmod((($g - $b) / $delta), 6),
            ($max === $g) => 60 * ((($b - $r) / $delta) + 2),
            ($max === $b) => 60 * ((($r - $g) / $delta) + 4),
            default => 0,
        };

        $hue = (round($hue) + 360) % 360; // normalize hue

        try {
            return new Color(
                intval(round($hue)),
                intval(round($saturation * 100)),
                intval(round($luminance * 100)),
                $color->alpha()->normalized(),
            );
        } catch (InvalidArgumentException $e) {
            throw new ColorException(
                'Failed to import color ' . $color::class . ' to ' . $this::class,
                previous: $e,
            );
        }
    }

    /**
     * Import given HSV color to HSL colorspace.
     *
     * @throws ColorException
     */
    private function importHsvColor(HsvColor $color): HslColor
    {
        // normalized values of hsv channels
        [$h, $s, $v] = array_map(
            fn(ColorChannelInterface $channel): float => $channel->normalized(),
            $color->channels(),
        );

View on GitHub (pinned to 5598b9e397)

Solutions

1. Check $e->getPrevious() for the exact channel and bound that failed
2. Ensure the source color's alpha()->normalized() returns a value clamped to [0,1]
3. Rebuild the source color from validated integers/floats before converting
4. If conversion of arbitrary colors must never fail, catch ColorException and fall back to a default Hsl\Color

Example fix

// before
$alpha = $row['opacity']; // e.g. 50 (percent scale)
$rgb = new RgbColor(255, 0, 0, $alpha);

// after
$alpha = $row['opacity'] / 100; // normalized scale
$rgb = new RgbColor(255, 0, 0, $alpha);

$alpha = $rgbColor->alpha()->normalized();
if ($alpha < 0.0 || $alpha > 1.0) {
    $rgbColor = Rgb\Color::create(
        $rgbColor->red()->value(),
        $rgbColor->green()->value(),
        $rgbColor->blue()->value(),
        min(1.0, max(0.0, $alpha)),
    );
}

use Intervention\Image\Exceptions\ColorException;

try {
    $hsl = $rgbColor->toColorspace(Hsl\Colorspace::class);
} catch (ColorException $e) {
    $hsl = Hsl\Color::create(0, 0, 0); // safe default
}

When it happens

Trigger: $rgbColor->toColorspace(Hsl\Colorspace::class) where the source color's alpha()->normalized() is outside 0.0-1.0 (custom color implementations, colors reconstructed from unvalidated storage), or NaN/infinite channel values producing invalid computed hue/saturation/luminance.

Common situations: Custom ColorInterface implementations or wrappers that return unnormalized alpha; colors unserialized from cache without re-validation; numerically corrupted channel data from external image analysis pipelines.

Related errors

• Unable to import color {colorClass} to {class}
• Failed to import color {color_class} to {colorspace_class}
• Failed to import color {colorClass} to {class}
• Unable to parse HSL color from input "{input}"
• Number of color channels must be 3 or 4 for {class}

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