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

Failed to import color {color_class} to {colorspace_class}

Error message

Failed to import color {color_class} to {colorspace_class}

What it means

Rgb\Colorspace::importColor() converts foreign colors to RGB via a match on the concrete class name. Only Cmyk\Color, Hsv\Color, Hsl\Color, Oklab\Color, Oklch\Color, NamedColor and Rgb\Color are handled; any other ColorInterface implementation (typically your own color class) falls to the default arm and throws ColorException. Subclasses of the built-in colors also fail, because the match is on the exact class name.

Source

Thrown at src/Colors/Rgb/Colorspace.php:88

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

    /**
     * @throws ColorException
     */
    private function importCmykColor(CmykColor $color): RgbColor
    {
        try {
            return new Color(
                (int) (255 * (1 - $color->cyan()->normalized()) * (1 - $color->key()->normalized())),
                (int) (255 * (1 - $color->magenta()->normalized()) * (1 - $color->key()->normalized())),
                (int) (255 * (1 - $color->yellow()->normalized()) * (1 - $color->key()->normalized())),
                $color->alpha()->normalized(),
            );
        } catch (InvalidArgumentException $e) {

View on GitHub (pinned to 5598b9e397)

Solutions

1. Pass a native built-in color object (exact class must be one of the seven supported classes)
2. For custom colors, convert to an Rgb\Color yourself before calling toColorspace()/importColor()
3. Unwrap decorators/proxies so the underlying native color instance is passed
4. Do not subclass built-in colors for conversions; use composition and convert explicitly

Example fix

// before
$rgb = (new \App\Colors\MyColor(0.2, 0.4, 0.9))->toColorspace(\Intervention\Image\Colors\Rgb\Colorspace::class);

// after
$my = new \App\Colors\MyColor(0.2, 0.4, 0.9);
$rgb = \Intervention\Image\Colors\Rgb\Color::create($my->r8(), $my->g8(), $my->b8());

$importable = [Cmyk\Color::class, Hsv\Color::class, Hsl\Color::class, Oklab\Color::class, Oklch\Color::class, NamedColor::class, Rgb\Color::class];
if (!in_array(get_class($color), $importable, true)) {
    throw new \RuntimeException('Color type not importable to RGB: ' . get_class($color));
}
$rgb = (new Rgb\Colorspace())->importColor($color);

function isImportableToRgb(\Intervention\Image\Interfaces\ColorInterface $color): bool
{
    return in_array(get_class($color), [
        \Intervention\Image\Colors\Cmyk\Color::class,
        \Intervention\Image\Colors\Hsv\Color::class,
        \Intervention\Image\Colors\Hsl\Color::class,
        \Intervention\Image\Colors\Oklab\Color::class,
        \Intervention\Image\Colors\Oklch\Color::class,
        \Intervention\Image\Colors\Rgb\NamedColor::class,
        \Intervention\Image\Colors\Rgb\Color::class,
    ], true); // exact class match; subclasses fail
}

try {
    $rgb = $color->toColorspace(\Intervention\Image\Colors\Rgb\Colorspace::class);
} catch (\Intervention\Image\Exceptions\ColorException $e) {
    // custom color class: convert manually to Rgb\Color
    $rgb = \Intervention\Image\Colors\Rgb\Color::create($my->r8(), $my->g8(), $my->b8());
}

When it happens

Trigger: Calling toColorspace(Rgb\Colorspace::class) or importColor() with an instance of a custom class implementing ColorInterface, a decorated/proxied color wrapper, or a color class from a third-party package extending the library.

Common situations: Adding a custom colorspace or wrapping colors with domain logic; decorator/proxy patterns where $color::class no longer equals a built-in class; subclassing Rgb\Color expecting the colorspace to still accept it.

Related errors

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