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

Failed to import color {colorClass} to {class}

Error message

Failed to import color {colorClass} to {class}

What it means

Thrown when Intervention Image converts an RgbColor to CMYK and the resulting Cmyk\Color constructor rejects the computed values. The original InvalidArgumentException (channel outside 0-100 or alpha outside 0.0-1.0) is re-thrown as a ColorException with the message 'Failed to import color ... to ...'. With a well-formed RgbColor this is nearly unreachable; it appears when the source color's alpha()->normalized() returns a value outside [0,1] or when degenerate/NaN values leak into the conversion math.

Source

Thrown at src/Colors/Cmyk/Colorspace.php:110

     * Import given RGB color to CMYK colorspace.
     *
     * @throws ColorException
     */
    private function importRgbColor(RgbColor $color): CmykColor
    {
        $c = (255 - $color->red()->value()) / 255.0 * 100;
        $m = (255 - $color->green()->value()) / 255.0 * 100;
        $y = (255 - $color->blue()->value()) / 255.0 * 100;
        $k = intval(round(min([$c, $m, $y])));

        $c = intval(round($c - $k));
        $m = intval(round($m - $k));
        $y = intval(round($y - $k));

        try {
            return new CmykColor($c, $m, $y, $k, $color->alpha()->normalized());
        } catch (InvalidArgumentException $e) {
            throw new ColorException(
                'Failed to import color ' . $color::class . ' to ' . $this::class,
                previous: $e,
            );
        }
    }

    /**
     * Import given color to CMYK colorspace by converting it to RGB first.
     *
     * @throws ColorException
     */
    private function importViaRgbColor(NamedColor|OklabColor|OklchColor|HslColor|HsvColor $color): CmykColor
    {
        try {
            $color = $color->toColorspace(RgbColorspace::class);
        } catch (InvalidArgumentException $e) {
            throw new ColorException(
                'Failed to import color ' . $color::class . ' to ' . $this::class,

View on GitHub (pinned to 5598b9e397)

Solutions

1. Inspect $e->getPrevious() in the caught ColorException - it carries the exact constructor message telling which channel was out of range
2. Fix the source color so alpha()->normalized() returns a float in [0,1] and all channel values are within their documented bounds
3. If you convert user-supplied channel values, clamp them before building the color: $alpha = min(1.0, max(0.0, $alpha))
4. As a last resort build the CMYK color manually with Cmyk\Color::create(int $c, int $m, int $y, int $k) after validating each value is an integer in 0-100

Example fix

// before (custom color returns unvalidated alpha)
$alpha = $this->storedAlpha * 1.5; // may exceed 1.0
return new RgbColor(255, 0, 0, $alpha);

// after
$alpha = min(1.0, max(0.0, $this->storedAlpha));
return new RgbColor(255, 0, 0, $alpha);

$alpha = $sourceColor->alpha()->normalized();
if (!is_finite($alpha) || $alpha < 0.0 || $alpha > 1.0) {
    throw new RuntimeException('Source color alpha out of range: ' . var_export($alpha, true));
}

use Intervention\Image\Exceptions\ColorException;

try {
    $cmyk = $color->toColorspace(Cmyk\Colorspace::class);
} catch (ColorException $e) {
    $reason = $e->getPrevious()?->getMessage() ?? $e->getMessage();
    // log $reason; fall back to a default CMYK color
    $cmyk = Cmyk\Color::create(0, 0, 0, 0);
}

When it happens

Trigger: Calling $rgbColor->toColorspace(Cmyk\Colorspace::class) or (new Cmyk\Colorspace())->importColor($rgbColor) where the source color object carries an out-of-range alpha (e.g. a custom ColorInterface implementation returning 1.5 or -0.1 from alpha()->normalized()), or float corruption (INF/NaN) in the red/green/blue channels.

Common situations: Custom color classes wrapping or decorating a library color (caching/serialization wrappers) that forward channel calls incorrectly; colors rebuilt from unserialized or database-stored channel values without re-validation; unit tests feeding hand-made color mocks with invalid alpha.

Related errors

• Invalid cmyk() color syntax "{input}"
• 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/4463bf6d1cbf0908. Report an issue: GitHub.