Intervention/image · error · ModifierException

Failed to apply Intervention\Image\Drivers\Imagick\Modifiers

Error message

Failed to apply Intervention\Image\Drivers\Imagick\Modifiers\ColorizeModifier, unable to get quantum range

What it means

Thrown by the Imagick ColorizeModifier when Imagick::getQuantumRange() throws while preparing per-channel levels for $image->colorize(). Note the catch targets the library's own ImageException, not ImagickException — so this specific wrapper only fires for that exception type; a raw ext-imagick failure would not enter this catch. The quantum range (max channel value, e.g. 255 vs 65535) is needed to build the levelImage() bounds.

Source

Thrown at src/Drivers/Imagick/Modifiers/ColorizeModifier.php:29

use Intervention\Image\Interfaces\SpecializedInterface;
use Intervention\Image\Modifiers\ColorizeModifier as GenericColorizeModifier;

class ColorizeModifier extends GenericColorizeModifier implements SpecializedInterface
{
    /**
     * @throws ModifierException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        $red = $this->normalizeLevel($this->red);
        $green = $this->normalizeLevel($this->green);
        $blue = $this->normalizeLevel($this->blue);

        foreach ($image as $frame) {
            try {
                $qrange = $frame->native()->getQuantumRange();
            } catch (ImageException $e) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to get quantum range',
                    previous: $e,
                );
            }

            try {
                $result = $frame->native()->levelImage(0, $red, $qrange['quantumRangeLong'], Imagick::CHANNEL_RED)
                    && $frame->native()->levelImage(0, $green, $qrange['quantumRangeLong'], Imagick::CHANNEL_GREEN)
                    && $frame->native()->levelImage(0, $blue, $qrange['quantumRangeLong'], Imagick::CHANNEL_BLUE);

                if ($result === false) {
                    throw new ModifierException(
                        'Failed to apply ' . self::class . ', unable to adjust image colors',
                    );
                }
            } catch (ImageException $e) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to adjust image colors',

View on GitHub (pinned to 5598b9e397)

Solutions

1. If you see this exact message, something raised Intervention\Image\Exceptions\ImageException inside the try — inspect the previous exception and fix that origin.
2. If you instead see an uncaught ImagickException from colorize(), catch ImagickException too in your calling code; the modifier's guard is narrower than ext-imagick's failure surface (a library-side catch-type mismatch worth reporting upstream).
3. Verify the imagick build: php -r 'var_dump((new Imagick)->getQuantumRange());' — if that fails, fix the extension/ImageMagick install.
4. Ensure the input frame decoded completely before colorizing.

Example fix

// before
try {
    $image->colorize(50, 0, -20);
} catch (\Intervention\Image\Exceptions\ModifierException $e) {
    // native ImagickException from getQuantumRange is NOT caught by the modifier
}

// after
try {
    $image->colorize(50, 0, -20);
} catch (\Intervention\Image\Exceptions\ModifierException | \ImagickException $e) {
    logger()->warning('colorize failed: ' . $e->getMessage());
}

// sanity-check the quantum range query on this build
try {
    (new \Imagick())->getQuantumRange();
} catch (\ImagickException $e) {
    throw new RuntimeException('imagick quantum range unavailable: ' . $e->getMessage());
}

use Intervention\Image\Exceptions\ModifierException;
try {
    $image->colorize(30, 0, -30);
} catch (ModifierException | \ImagickException $e) {
    // include ImagickException: the modifier's catch is narrower than native failures
    logger()->warning('colorize failed', ['msg' => $e->getMessage()]);
}

When it happens

Trigger: Calling $image->colorize($red, $green, $blue) where getQuantumRange() on a frame's native wand fails. Because the guard does not match ImagickException, native ext-imagick failures typically escape uncaught instead — the documented throw fires only for Intervention ImageException being raised at that call site.

Common situations: Colorizing on exotic builds (high-bit-depth HDRI ImageMagick) where quantum queries behave unexpectedly; code that previously wrapped the native handle and threw library-typed exceptions from inside; diagnosing colorize failures that appear as raw ImagickException rather than ModifierException is the usual real-world encounter with this region.

Related errors

• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• 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/704c82034b523241. Report an issue: GitHub.