{"record":{"id":"9cbae457949561e4","repo":"Intervention/image","slug":"failed-to-apply-class-unable-to-process-unsharp","errorCode":null,"errorMessage":"Failed to apply {class}, unable to process unsharp mask","messagePattern":"Failed to apply (.+?), unable to process unsharp mask","errorType":"exception","errorClass":"Intervention\\Image\\Exceptions\\ModifierException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Modifiers/SharpenModifier.php","lineNumber":24,"sourceCode":"\nuse ImagickException;\nuse Intervention\\Image\\Exceptions\\ModifierException;\nuse Intervention\\Image\\Interfaces\\ImageInterface;\nuse Intervention\\Image\\Interfaces\\SpecializedInterface;\nuse Intervention\\Image\\Modifiers\\SharpenModifier as GenericSharpenModifier;\n\nclass SharpenModifier extends GenericSharpenModifier implements SpecializedInterface\n{\n    /**\n     * @throws ModifierException\n     */\n    public function apply(ImageInterface $image): ImageInterface\n    {\n        foreach ($image as $frame) {\n            try {\n                $result = $frame->native()->unsharpMaskImage(1, 1, $this->level / 6.25, 0);\n                if ($result === false) {\n                    throw new ModifierException(\n                        'Failed to apply ' . self::class . ', unable to process unsharp mask',\n                    );\n                }\n            } catch (ImagickException $e) {\n                throw new ModifierException(\n                    'Failed to apply ' . self::class . ', unable to process unsharp mask',\n                    previous: $e,\n                );\n            }\n        }\n\n        return $image;\n    }\n}\n","sourceCodeStart":6,"sourceCodeEnd":39,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Modifiers/SharpenModifier.php#L6-L39","documentation":"Thrown by the Imagick SharpenModifier when Imagick::unsharpMaskImage(1, 1, $level / 6.25, 0) returns false while applying to a frame. The sharpen level (0-100) is divided by 6.25 to become the unsharp amount, so the parameters themselves are always in a sane range - a false return means ImageMagick refused the operation, typically because the frame's native object is empty or in an invalid state.","triggerScenarios":"$image->sharpen(30) (any level) on the Imagick driver when unsharpMaskImage() returns false for a frame: images created without pixel data, frames left inconsistent by an earlier modifier that failed midway, or ImageMagick builds rejecting the operation for the frame's colorspace.","commonSituations":"Reusing an image object after catching an exception from a previous modifier in the same chain; sharpening blank/programmatically created images before content is drawn; CMYK or exotic colorspace sources on certain ImageMagick versions.","solutions":["Re-read the image from its source and apply ->sharpen() as the first modifier to rule out corrupted frame state","Check $image->count() and that the frame actually has pixel data before sharpening","Convert the image to sRGB before sharpening if the source is CMYK or another exotic colorspace","Reproduce with a raw Imagick script (unsharpMaskImage(1, 1, 4.8, 0)) on the same file to isolate an ImageMagick build issue"],"exampleFix":"// before\n$image->sharpen(30); // ModifierException: unable to process unsharp mask\n\n// after: fresh decode, sharpen first\n$image = $manager->read($path);\n$image->sharpen(30);","handlingStrategy":"try-catch","validationCode":"// sharpen only images that hold pixel data\nif ($image->count() === 0 || $image->width() < 1 || $image->height() < 1) {\n    throw new InvalidArgumentException('Image has no pixel data to sharpen');\n}\n$image->sharpen($level);","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\ModifierException;\n\ntry {\n    $image->sharpen($level);\n} catch (ModifierException $e) {\n    $logger->warning('Sharpen returned failure: ' . $e->getMessage());\n    // sharpening is cosmetic - continue without it if acceptable\n}","preventionTips":["Apply sharpen on freshly decoded images rather than objects that survived earlier exceptions","Keep sharpen early in the chain, before format/colourspace conversions","Test the pipeline against the colorspaces your users actually upload (CMYK, greyscale)"],"tags":["imagick","sharpen","unsharp-mask","modifier"],"backgroundTag":"imagick-operation-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}