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

Unable to import color {color_class} to {colorspace_class}

Error message

Unable to import color {color_class} to {colorspace_class}

What it means

Oklch\Colorspace::importColor() matches on the exact class of the incoming color and supports only CmykColor, HsvColor, NamedColor, HslColor, OklabColor, RgbColor and OklchColor; any other class hits the default arm and throws ColorException (src/Colors/Oklch/Colorspace.php:79-93). Because the match uses $color::class, subclasses of supported colors are also rejected.

Source

Thrown at src/Colors/Oklch/Colorspace.php:89

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

    /**
     * Import given OKLAB color OKLCH colorspace.
     *
     * @throws ColorException
     */
    private function importOklabColor(OklabColor $color): OklchColor
    {
        $a = $color->a()->value();
        $b = $color->b()->value();

        $c = sqrt($a * $a + $b * $b);
        $h = rad2deg(atan2($b, $a));
        $h = $h < 0 ? $h + 360 : $h;

View on GitHub (pinned to 5598b9e397)

Solutions

1. Convert custom colors to Rgb\Color (or another supported exact class) before toColorspace()
2. Compose built-in colors instead of subclassing them when interoperating with the library
3. Keep Intervention Image updated so newer colorspaces are listed in the match
4. Catch ColorException and handle/report the unsupported class name

Example fix

// before
$oklch = $customColor->toColorspace(Oklch\Colorspace::class); // ColorException: Unable to import color ...

// after
$rgb = Rgb\Color::create($customColor->r, $customColor->g, $customColor->b);
$oklch = $rgb->toColorspace(Oklch\Colorspace::class);

$supported = [
    CmykColor::class, HsvColor::class, NamedColor::class, HslColor::class,
    OklabColor::class, RgbColor::class, OklchColor::class,
];
if (!in_array($color::class, $supported, true)) {
    $color = $color->toColorspace(Rgb\Colorspace::class);
}
$oklch = $color->toColorspace(Oklch\Colorspace::class);

function isImportableToOklch(ColorInterface $color): bool
{
    return in_array($color::class, [
        CmykColor::class, HsvColor::class, NamedColor::class, HslColor::class,
        OklabColor::class, RgbColor::class, OklchColor::class,
    ], true);
}

try {
    $oklch = $color->toColorspace(Oklch\Colorspace::class);
} catch (ColorException $e) {
    // unsupported class: convert to RgbColor and retry, or report upstream
}

When it happens

Trigger: Calling $color->toColorspace(Oklch\Colorspace::class) with a custom ColorInterface implementation, an anonymous/subclassed color, or a color class unknown to the installed version of the library.

Common situations: Application-specific color value objects fed to library APIs; wrappers that extend built-in color classes; upgrading/downgrading across versions where color classes were added.

Related errors

• Unable to import color {color_class} to {colorspace_class}
• Failed to import color {color_class} to {colorspace_class}
• Failed to import color {color_class} to {colorspace_class}
• Unable to parse OKLCH 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/17facb872855ab40. Report an issue: GitHub.