Intervention/image · error · NotSupportedException

Colorspace {colorspace::class} is not supported by driver

Error message

Colorspace {colorspace::class} is not supported by driver

What it means

Thrown by ColorspaceModifier::imagickColorspaceOrFail() when the target colorspace class has no Imagick mapping. Supported: Rgb, Cmyk, Hsl, Hsv, and Oklab/Oklch only when the corresponding Imagick constants exist. Any other ColorspaceInterface implementation — including Oklab/Oklch on old builds lacking COLORSPACE_OKLAB/COLORSPACE_OKLCH — gets this NotSupportedException.

Source

Thrown at src/Drivers/Imagick/Modifiers/ColorspaceModifier.php:91

            return Imagick::COLORSPACE_HSB;
        }

        try {
            if ($colorspace instanceof Oklab && defined(Imagick::class . '::COLORSPACE_OKLAB')) {
                return constant(Imagick::class . '::COLORSPACE_OKLAB');
            }

            if ($colorspace instanceof Oklch && defined(Imagick::class . '::COLORSPACE_OKLCH')) {
                return constant(Imagick::class . '::COLORSPACE_OKLCH');
            }
        } catch (Error $e) {
            throw new ModifierException(
                'Failed to convert colorspace to Imagick constant',
                previous: $e,
            );
        }

        throw new NotSupportedException('Colorspace ' . $colorspace::class . ' is not supported by driver');
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Target one of the always-supported colorspaces: Rgb, Cmyk, Hsl or Hsv.
2. For Oklab/Oklch, upgrade ImageMagick (>= 7.1-ish) and the pecl/imagick extension so the constants exist: php -r 'var_dump(defined("\\Imagick::COLORSPACE_OKLAB"));'.
3. If you authored a custom colorspace, add a driver-supported path or map it to the nearest supported one (e.g. sRGB) instead of passing it to the Imagick driver.
4. Feature-detect before calling (see validation guard) so deployments degrade gracefully across environments.

Example fix

// before
$image->colorspace(\Intervention\Image\Colors\Oklch\Colorspace::class); // old imagick -> NotSupportedException

// after
$target = defined(\Imagick::class . '::COLORSPACE_OKLCH')
    ? \Intervention\Image\Colors\Oklch\Colorspace::class
    : \Intervention\Image\Colors\Rgb\Colorspace::class;
$image->colorspace($target);

use Intervention\Image\Colors\{Rgb\Colorspace as Rgb, Cmyk\Colorspace as Cmyk, Hsl\Colorspace as Hsl, Hsv\Colorspace as Hsv, Oklab\Colorspace as Oklab, Oklch\Colorspace as Oklch};

function isSupportedByImagickDriver(string $colorspace): bool
{
    return match ($colorspace) {
        Rgb::class, Cmyk::class, Hsl::class, Hsv::class => true,
        Oklab::class => defined(\Imagick::class . '::COLORSPACE_OKLAB'),
        Oklch::class => defined(\Imagick::class . '::COLORSPACE_OKLCH'),
        default => false,
    };
}

function supportedColorspaceOrDefault(string $colorspace, string $default = \Intervention\Image\Colors\Rgb\Colorspace::class): string
{
    $map = [
        \Intervention\Image\Colors\Rgb\Colorspace::class => true,
        \Intervention\Image\Colors\Cmyk\Colorspace::class => true,
        \Intervention\Image\Colors\Hsl\Colorspace::class => true,
        \Intervention\Image\Colors\Hsv\Colorspace::class => true,
        \Intervention\Image\Colors\Oklab\Colorspace::class => defined(\Imagick::class . '::COLORSPACE_OKLAB'),
        \Intervention\Image\Colors\Oklch\Colorspace::class => defined(\Imagick::class . '::COLORSPACE_OKLCH'),
    ];
    return ($map[$colorspace] ?? false) ? $colorspace : $default;
}

use Intervention\Image\Exceptions\NotSupportedException;
try {
    $image->colorspace($target);
} catch (NotSupportedException $e) {
    // degrade to sRGB rather than failing the request
    $image->colorspace(\Intervention\Image\Colors\Rgb\Colorspace::class);
}

When it happens

Trigger: Passing a custom colorspace class implementing ColorspaceInterface to $image->colorspace(); targeting Oklab or Oklch on ImageMagick/ext-imagick builds older than the constants' introduction; passing an enum/string value that resolves to an unmapped class.

Common situations: Using newer library features (Oklab/Oklch) on a server pinned to older ImageMagick; custom colorspaces written for the GD driver reused with Imagick; CI passing (new ImageMagick) while production fails (old one).

Related errors

• Failed to convert colorspace to Imagick constant
• Failed to import color {color_class} to {colorspace_class}
• Colorspace
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers

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