Intervention/image · error · NotSupportedException

Only RGB colorspace is supported by GD driver

Error message

Only RGB colorspace is supported by GD driver

What it means

GD has no colorspace conversion capability and only operates in RGB. The ColorspaceModifier therefore rejects any target colorspace that is not an RgbColorspace — for example converting to cmyk or gray — with NotSupportedException, while leaving RGB targets as a no-op.

Source

Thrown at src/Drivers/Gd/Modifiers/ColorspaceModifier.php:25

use Intervention\Image\Colors\Rgb\Colorspace as RgbColorspace;
use Intervention\Image\Exceptions\NotSupportedException;
use Intervention\Image\Interfaces\ImageInterface;
use Intervention\Image\Interfaces\SpecializedInterface;
use Intervention\Image\Modifiers\ColorspaceModifier as GenericColorspaceModifier;

class ColorspaceModifier extends GenericColorspaceModifier implements SpecializedInterface
{
    /**
     * {@inheritdoc}
     *
     * @see ModifierInterface::apply()
     *
     * @throws NotSupportedException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        if (!$this->targetColorspace() instanceof RgbColorspace) {
            throw new NotSupportedException(
                'Only RGB colorspace is supported by GD driver',
            );
        }

        return $image;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Use ->greyscale() for grayscale output on the GD driver
2. Switch the manager to the Imagick driver when CMYK conversion is actually required
3. Gate colorspace calls by driver capability before invoking them
4. Convert colorspace in an external tool (ImageMagick CLI) if GD must stay

Example fix

// before
$image = $manager->read('print.tif');
$image->colorspace('cmyk'); // NotSupportedException on GD

// after
$imagickManager = ImageManager::usingDriver(ImagickDriver::class);
$image = $imagickManager->read('print.tif');
$image->colorspace('cmyk');

$allowed = ['rgb', 'srgb'];
if (!in_array(strtolower($target), $allowed, true) && usingGdDriver($manager)) {
    throw new RuntimeException('GD supports only RGB; use Imagick for ' . $target);
}
$image->colorspace($target);

try {
    $image->colorspace($target);
} catch (NotSupportedException $e) {
    $image = ImageManager::usingDriver(ImagickDriver::class)->read($source);
    $image->colorspace($target);
}

When it happens

Trigger: $image->colorspace('cmyk') or ->colorspace('gray') while the manager runs on the GD driver.

Common situations: Print workflows assuming CMYK output, code shared between drivers that works under Imagick but is deployed with GD, attempts to get grayscale via colorspace() instead of ->greyscale().

Related errors

• Failed to normalize background color to RGB color space
• Failed to normalize background color to RGB color space
• Failed to normalize background color to RGB color space
• Failed to convert background color to RGB color space
• Failed to normalize background color to RGB color space

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