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

Unable to import color {colorClass} to {class}

Error message

Unable to import color {colorClass} to {class}

What it means

Hsl\Colorspace::importColor() dispatches on the concrete class of the incoming color and supports only HslColor, HsvColor, RgbColor, CmykColor, NamedColor, OklabColor and OklchColor. Any other ColorInterface implementation falls through to a default arm that throws this ColorException ('Unable to import color X to Y'). It is a supported-type check, not a data validation failure.

Source

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

    /**
     * {@inheritdoc}
     *
     * @see ColorspaceInterface::importColor()
     *
     * @throws ColorException
     */
    public function importColor(ColorInterface $color): HslColor
    {
        return match ($color::class) {
            HslColor::class => $color,
            OklchColor::class,
            OklabColor::class,
            NamedColor::class,
            CmykColor::class => $this->importViaRgbColor($color),
            RgbColor::class => $this->importRgbColor($color),
            HsvColor::class => $this->importHsvColor($color),
            default => throw new ColorException(
                'Unable to import color ' . $color::class . ' to ' . $this::class,
            ),
        };
    }

    /**
     * Import given RGB color to HSL colorspace.
     *
     * @throws ColorException
     */
    private function importRgbColor(RgbColor $color): HslColor
    {
        // normalized values of rgb channels
        $values = array_map(
            fn(ColorChannelInterface $channel): float => $channel->normalized(),
            $color->channels(),
        );

View on GitHub (pinned to 5598b9e397)

Solutions

1. Convert through RGB first: $color->toColorspace(Rgb\Colorspace::class) returns a supported RgbColor (if your class delegates conversion), then ->toColorspace(Hsl\Colorspace::class)
2. Unwrap decorators and pass the underlying built-in color instance to the import
3. Make your custom class extend one of the supported colors (e.g. extend HslColor or RgbColor) so the match arm hits
4. Register/handle your type before calling importColor and convert it yourself to Hsl\Color::create(...)

Example fix

// before
$hsl = $customColor->toColorspace(Hsl\Colorspace::class); // custom class not matched

// after
$rgb = $customColor->toRgb(); // your own conversion to a built-in RgbColor
$hsl = $rgb->toColorspace(Hsl\Colorspace::class);

$supported = [HslColor::class, HsvColor::class, RgbColor::class, CmykColor::class, NamedColor::class, OklabColor::class, OklchColor::class];
if (!in_array(get_class($color), $supported, true)) {
    $color = $color->toColorspace(Rgb\Colorspace::class); // normalize to a built-in first
}

function isHslImportable(ColorInterface $color): bool
{
    return $color instanceof HslColor
        || $color instanceof HsvColor
        || $color instanceof RgbColor
        || $color instanceof CmykColor
        || $color instanceof NamedColor
        || $color instanceof OklabColor
        || $color instanceof OklchColor;
}

use Intervention\Image\Exceptions\ColorException;

try {
    $hsl = $color->toColorspace(Hsl\Colorspace::class);
} catch (ColorException $e) {
    // unsupported source class; convert manually or reject
}

When it happens

Trigger: $color->toColorspace(Hsl\Colorspace::class) where $color is a custom class implementing ColorInterface but extending none of the supported built-ins - e.g. a decorator, a legacy adapter, or a subclass of AbstractColor that is not one of the seven listed classes.

Common situations: Value objects wrapping a library color for caching, DTOs, or ORM embedding; projects upgrading custom color code from earlier library versions; test doubles implementing the interface directly.

Related errors

• Failed to import color {colorClass} to {class}
• Unable 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/7c47e1ffb93b143a. Report an issue: GitHub.