Intervention/image · error · ColorException

Failed to convert named color to rgb object

Error message

Failed to convert named color to rgb object

What it means

NamedColor converts itself to an Rgb\Color internally by importing the color through the RGB colorspace and verifying the result is an RgbColor. This exception means the conversion produced a different ColorInterface implementation. With the built-in RGB colorspace this is an internal invariant violation; in practice it appears when a custom colorspace whose importColor() does not return RgbColor is in play.

Source

Thrown at src/Colors/Rgb/NamedColor.php:500

     * @throws ColorException
     */
    public function withInversion(): ColorInterface
    {
        return $this->toRgbColor()->withInversion();
    }

    /**
     * Convert current named color to rgb color object.
     *
     * @throws ColorException
     */
    private function toRgbColor(): RgbColor
    {
        $color = $this->colorspace()->importColor($this);

        return $color instanceof RgbColor
            ? $color
            : throw new ColorException('Failed to convert named color to rgb object');
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Fix the custom colorspace's importColor() so importing a named color returns an RgbColor instance
2. Replace the custom colorspace with the stock Intervention\Image\Colors\Rgb\Colorspace
3. If no custom colorspace is involved, report the bug upstream with a reproduction case

try {
    $isGray = $namedColor->isGrayscale();
} catch (ColorException $e) {
    // colorspace misconfiguration; verify custom colorspace implementations
}

When it happens

Trigger: Calling channels(), channel(), toColorspace(), isGrayscale(), withTransparency(), withBrightness(), withSaturation() or withInversion() on a NamedColor case while a custom colorspace implementation returns a non-RgbColor from importColor().

Common situations: Custom colorspace classes added for CMYK/HSL experiments that override importColor(); forks that alter the stock Rgb colorspace's return types.

Related errors

• Unable to import color {color_class} to {colorspace_class}
• 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}"

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