{"record":{"id":"704c82034b523241","repo":"Intervention/image","slug":"failed-to-apply-intervention-image-drivers-imagick-704c82","errorCode":null,"errorMessage":"Failed to apply Intervention\\Image\\Drivers\\Imagick\\Modifiers\\ColorizeModifier, unable to get quantum range","messagePattern":"Failed to apply Intervention\\\\Image\\\\Drivers\\\\Imagick\\\\Modifiers\\\\ColorizeModifier, unable to get quantum range","errorType":"exception","errorClass":"ModifierException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Modifiers/ColorizeModifier.php","lineNumber":29,"sourceCode":"use Intervention\\Image\\Interfaces\\SpecializedInterface;\nuse Intervention\\Image\\Modifiers\\ColorizeModifier as GenericColorizeModifier;\n\nclass ColorizeModifier extends GenericColorizeModifier implements SpecializedInterface\n{\n    /**\n     * @throws ModifierException\n     */\n    public function apply(ImageInterface $image): ImageInterface\n    {\n        $red = $this->normalizeLevel($this->red);\n        $green = $this->normalizeLevel($this->green);\n        $blue = $this->normalizeLevel($this->blue);\n\n        foreach ($image as $frame) {\n            try {\n                $qrange = $frame->native()->getQuantumRange();\n            } catch (ImageException $e) {\n                throw new ModifierException(\n                    'Failed to apply ' . self::class . ', unable to get quantum range',\n                    previous: $e,\n                );\n            }\n\n            try {\n                $result = $frame->native()->levelImage(0, $red, $qrange['quantumRangeLong'], Imagick::CHANNEL_RED)\n                    && $frame->native()->levelImage(0, $green, $qrange['quantumRangeLong'], Imagick::CHANNEL_GREEN)\n                    && $frame->native()->levelImage(0, $blue, $qrange['quantumRangeLong'], Imagick::CHANNEL_BLUE);\n\n                if ($result === false) {\n                    throw new ModifierException(\n                        'Failed to apply ' . self::class . ', unable to adjust image colors',\n                    );\n                }\n            } catch (ImageException $e) {\n                throw new ModifierException(\n                    'Failed to apply ' . self::class . ', unable to adjust image colors',","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Modifiers/ColorizeModifier.php#L11-L47","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["If you see this exact message, something raised Intervention\\Image\\Exceptions\\ImageException inside the try — inspect the previous exception and fix that origin.","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).","Verify the imagick build: php -r 'var_dump((new Imagick)->getQuantumRange());' — if that fails, fix the extension/ImageMagick install.","Ensure the input frame decoded completely before colorizing."],"exampleFix":"// before\ntry {\n    $image->colorize(50, 0, -20);\n} catch (\\Intervention\\Image\\Exceptions\\ModifierException $e) {\n    // native ImagickException from getQuantumRange is NOT caught by the modifier\n}\n\n// after\ntry {\n    $image->colorize(50, 0, -20);\n} catch (\\Intervention\\Image\\Exceptions\\ModifierException | \\ImagickException $e) {\n    logger()->warning('colorize failed: ' . $e->getMessage());\n}","handlingStrategy":"try-catch","validationCode":"// sanity-check the quantum range query on this build\ntry {\n    (new \\Imagick())->getQuantumRange();\n} catch (\\ImagickException $e) {\n    throw new RuntimeException('imagick quantum range unavailable: ' . $e->getMessage());\n}","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\ModifierException;\ntry {\n    $image->colorize(30, 0, -30);\n} catch (ModifierException | \\ImagickException $e) {\n    // include ImagickException: the modifier's catch is narrower than native failures\n    logger()->warning('colorize failed', ['msg' => $e->getMessage()]);\n}","preventionTips":["Catch both ModifierException and ImagickException around colorize() — the driver guard does not cover native throws.","Verify getQuantumRange() works on target hosts during deployment smoke tests.","Prefer 8-bit non-HDRI ImageMagick builds unless you specifically need deep color."],"tags":["imagick","colorize","quantum-range","modifier-exception","bit-depth"],"backgroundTag":"image-modifier-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}