{"record":{"id":"acef6951f3933c5d","repo":"Intervention/image","slug":"failed-to-set-image-contrast","errorCode":null,"errorMessage":"Failed to set image contrast","messagePattern":"Failed to set image contrast","errorType":"exception","errorClass":"ModifierException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Modifiers/ContrastModifier.php","lineNumber":26,"sourceCode":"use Intervention\\Image\\Interfaces\\ImageInterface;\nuse Intervention\\Image\\Interfaces\\SpecializedInterface;\nuse Intervention\\Image\\Modifiers\\ContrastModifier as GenericContrastModifier;\n\nclass ContrastModifier extends GenericContrastModifier implements SpecializedInterface\n{\n    /**\n     * {@inheritdoc}\n     *\n     * @see ModifierInterface::apply()\n     *\n     * @throws ModifierException\n     */\n    public function apply(ImageInterface $image): ImageInterface\n    {\n        foreach ($image as $frame) {\n            $result = imagefilter($frame->native(), IMG_FILTER_CONTRAST, ($this->level * -1));\n            if ($result === false) {\n                throw new ModifierException('Failed to set image contrast');\n            }\n        }\n\n        return $image;\n    }\n}\n","sourceCodeStart":8,"sourceCodeEnd":33,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Modifiers/ContrastModifier.php#L8-L33","documentation":"The GD driver applies contrast by calling imagefilter($gd, IMG_FILTER_CONTRAST, -$level) on every frame and throws this ModifierException as soon as imagefilter() returns false. The level itself is not the issue (any int is accepted); a false return means GD could not run the filter on that native GdImage at all. Frames decoded through the driver are always converted to truecolor first, so in a clean pipeline this path is practically unreachable - it signals corrupted native state or an image GD refuses to filter.","triggerScenarios":"Calling $image->contrast($level) on frames whose native GdImage was replaced or invalidated by custom code (setNative() with a broken resource, manual imagedestroy(), hand-built Core objects); applying the filter to palette-based frames produced outside the normal decode path; the library's own test suite forcing imagefilter() to fail (testApplyThrowsWhenSpecializedWithoutOverride).","commonSituations":"Mixing raw GD resource manipulation with Intervention objects; long-lived workers that free GD resources while image objects survive; exotic or broken GD builds; unit tests deliberately exercising the failure branch.","solutions":["Re-decode the image from its original source and apply contrast() to the fresh instance","If frames were turned into palette images (e.g. after reduceColors()), convert them back first: foreach ($image as $frame) { imagepalettetotruecolor($frame->native()); }","Verify the GD installation (php -i | grep -i gd, gd_info()) on the failing host","Catch ModifierException and skip the effect or fall back to a manual pixel loop"],"exampleFix":"// before: contrast applied to frames that are no longer filterable\n$image->reduceColors(64)->contrast(30);\n\n// after: return frames to truecolor before filtering\n$image->reduceColors(64);\nforeach ($image as $frame) {\n    imagepalettetotruecolor($frame->native());\n}\n$image->contrast(30);","handlingStrategy":"try-catch","validationCode":"foreach ($image as $frame) {\n    $native = $frame->native();\n    if (!$native instanceof GdImage || imagesx($native) < 1) {\n        throw new RuntimeException('Frame native is not a usable GdImage');\n    }\n    if (!imageistruecolor($native)) {\n        imagepalettetotruecolor($native);\n    }\n}\n\n$image->contrast(30);","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\ModifierException;\n\ntry {\n    $image->contrast(30);\n} catch (ModifierException $e) {\n    $logger?->warning('Contrast filter failed: ' . $e->getMessage());\n    // keep the unmodified image\n}","preventionTips":["Decode and modify images through the same driver pipeline; do not swap native GdImage resources behind the library's back.","After reduceColors(), convert frames back to truecolor before applying GD filter effects.","Run gd_info() after deploying to a new environment to confirm filter support."],"tags":["gd","contrast","imagefilter","filter-failure","native-resource"],"backgroundTag":"gd-imagefilter-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}