{"record":{"id":"10ff7d2f39b55c24","repo":"Intervention/image","slug":"failed-to-apply-intervention-image-drivers-gd-modi-10ff7d","errorCode":null,"errorMessage":"Failed to apply Intervention\\Image\\Drivers\\Gd\\Modifiers\\GrayscaleModifier, unable to transform image to grayscale","messagePattern":"Failed to apply Intervention\\\\Image\\\\Drivers\\\\Gd\\\\Modifiers\\\\GrayscaleModifier, unable to transform image to grayscale","errorType":"exception","errorClass":"ModifierException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Modifiers/GrayscaleModifier.php","lineNumber":26,"sourceCode":"use Intervention\\Image\\Interfaces\\ImageInterface;\nuse Intervention\\Image\\Interfaces\\SpecializedInterface;\nuse Intervention\\Image\\Modifiers\\GrayscaleModifier as GenericGrayscaleModifier;\n\nclass GrayscaleModifier extends GenericGrayscaleModifier 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_GRAYSCALE);\n            if ($result === false) {\n                throw new ModifierException(\n                    'Failed to apply ' . self::class . ', unable to transform image to grayscale',\n                );\n            }\n        }\n\n        return $image;\n    }\n}\n","sourceCodeStart":8,"sourceCodeEnd":35,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Modifiers/GrayscaleModifier.php#L8-L35","documentation":"The GD driver converts each frame to grayscale with imagefilter($gd, IMG_FILTER_GRAYSCALE) and throws ModifierException when the call returns false. A driver-decoded frame is always a truecolor GdImage on which this filter succeeds, so a false return means the native image is not in a state GD can filter - an invalid or destroyed GdImage, or a frame converted to a palette image outside the normal pipeline. There are no parameters to get wrong: grayscale() takes none.","triggerScenarios":"$image->grayscale() after custom code invalidated frame natives (setNative() with a broken GdImage, manual imagedestroy()); filtering palette frames produced by hand-built cores; the library's test suite forcing imagefilter() to fail (testApplyThrowsWhenSpecializedWithoutOverride).","commonSituations":"Long-lived worker processes that keep image objects alive while raw GD resources were freed; raw GD interop layers; test doubles forcing imagefilter() to fail.","solutions":["Re-create the image from its source and apply grayscale() to the fresh instance","Ensure nothing destroyed or replaced frame natives (audit custom setNative()/imagedestroy() usage)","Convert palette frames back to truecolor: foreach ($image as $frame) { imagepalettetotruecolor($frame->native()); }","Catch ModifierException and skip the effect"],"exampleFix":"// before: grayscale on possibly corrupted native frames\n$image->grayscale();\n\n// after: decode fresh, normalize, then filter\n$image = $manager->decode($sourceBinary);\nforeach ($image as $frame) {\n    if (!imageistruecolor($frame->native())) {\n        imagepalettetotruecolor($frame->native());\n    }\n}\n$image->grayscale();","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->grayscale();","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\ModifierException;\n\ntry {\n    $image->grayscale();\n} catch (ModifierException $e) {\n    $logger?->warning('Grayscale filter failed: ' . $e->getMessage());\n}","preventionTips":["Do not free or replace native GD resources while image objects are still in use.","Decode and modify through the same driver pipeline.","Normalize palette frames back to truecolor before applying GD filters."],"tags":["gd","grayscale","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"}