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

Oklab\Colorspace::importColor() dispatches on the exact class name of the color via match ($color::class) and only knows CmykColor, HsvColor, NamedColor, HslColor, RgbColor, OklchColor and OklabColor; everything else hits the default arm and throws ColorException (src/Colors/Oklab/Colorspace.php:74-88). Note the match is on the exact class, so even a subclass of a known color (e.g. a custom class extending Rgb\Color) is rejected.

Source

Thrown at src/Colors/Oklab/Colorspace.php:84

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

    /**
     * Import given RGB color OKLAB colorspace.
     *
     * @throws ColorException
     */
    private function importRgbColor(RgbColor $color): OklabColor
    {
        $cbrt = fn(float $x): float => $x < 0 ? -abs($x) ** (1 / 3) : $x ** (1 / 3);
        $rgbToLinear = fn(float $x): float => $x <= 0.04045 ? $x / 12.92 : (($x + 0.055) / 1.055) ** 2.4;

        $r = $color->red()->normalized();
        $g = $color->green()->normalized();
        $b = $color->blue()->normalized();

View on GitHub (pinned to 5598b9e397)

Solutions

1. Convert custom colors to a supported class first, typically Rgb\Color, before toColorspace()
2. If you subclass a built-in color, pass an instance of the exact base class (compose instead of extend)
3. Upgrade Intervention Image so newly introduced colorspaces are recognized
4. Catch ColorException at conversion boundaries and report the unsupported class name

Example fix

// before
$oklab = $myCustomColor->toColorspace(Oklab\Colorspace::class); // ColorException: Unable to import color ...

// after
// convert your custom color to a supported intermediate first
$rgb = new Rgb\Color($myCustomColor->red(), $myCustomColor->green(), $myCustomColor->blue());
$oklab = $rgb->toColorspace(Oklab\Colorspace::class);

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

function isImportableToOklab(ColorInterface $color): bool
{
    return in_array($color::class, [
        CmykColor::class, HsvColor::class, NamedColor::class, HslColor::class,
        RgbColor::class, OklchColor::class, OklabColor::class,
    ], true); // exact class match, subclasses included in NO arm
}

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

When it happens

Trigger: Calling $color->toColorspace(Oklab\Colorspace::class) or Oklab\Colorspace::importColor() with a custom ColorInterface implementation, an anonymous subclass of a known color, or a color class added by a newer/older version than the running one.

Common situations: Application-defined color value objects passed into library APIs; third-party packages wrapping or extending the color classes; version mismatches where a colorspace class exists but is not listed in this match arm yet.

Related errors

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