Intervention/image · error · ModifierException

Failed to apply…

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.

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());
}
Defensive patterns

Strategy: try-catch

Validate before calling

// 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());
}

Try / catch

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()]);
}

Prevention

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

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

Appendix: 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)