Intervention/image · error · Intervention\Image\Exceptions\ModifierException

Failed to apply {class}, unable to process unsharp mask

Error message

Failed to apply {class}, unable to process unsharp mask

What it means

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.

Source

Thrown at src/Drivers/Imagick/Modifiers/SharpenModifier.php:24

use ImagickException;
use Intervention\Image\Exceptions\ModifierException;
use Intervention\Image\Interfaces\ImageInterface;
use Intervention\Image\Interfaces\SpecializedInterface;
use Intervention\Image\Modifiers\SharpenModifier as GenericSharpenModifier;

class SharpenModifier extends GenericSharpenModifier implements SpecializedInterface
{
    /**
     * @throws ModifierException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        foreach ($image as $frame) {
            try {
                $result = $frame->native()->unsharpMaskImage(1, 1, $this->level / 6.25, 0);
                if ($result === false) {
                    throw new ModifierException(
                        'Failed to apply ' . self::class . ', unable to process unsharp mask',
                    );
                }
            } catch (ImagickException $e) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to process unsharp mask',
                    previous: $e,
                );
            }
        }

        return $image;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Re-read the image from its source and apply ->sharpen() as the first modifier to rule out corrupted frame state
2. Check $image->count() and that the frame actually has pixel data before sharpening
3. Convert the image to sRGB before sharpening if the source is CMYK or another exotic colorspace
4. Reproduce with a raw Imagick script (unsharpMaskImage(1, 1, 4.8, 0)) on the same file to isolate an ImageMagick build issue

Example fix

// before
$image->sharpen(30); // ModifierException: unable to process unsharp mask

// after: fresh decode, sharpen first
$image = $manager->read($path);
$image->sharpen(30);

// sharpen only images that hold pixel data
if ($image->count() === 0 || $image->width() < 1 || $image->height() < 1) {
    throw new InvalidArgumentException('Image has no pixel data to sharpen');
}
$image->sharpen($level);

use Intervention\Image\Exceptions\ModifierException;

try {
    $image->sharpen($level);
} catch (ModifierException $e) {
    $logger->warning('Sharpen returned failure: ' . $e->getMessage());
    // sharpening is cosmetic - continue without it if acceptable
}

When it happens

Trigger: $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.

Common situations: 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.

Related errors

• Class '{objectShortname}' is not supported by {id} driver
• Failed to apply ' . self::class . ', unable to processs imag
• Failed to apply ' . self::class . ', unable to draw pixel on
• Given color space must implement Intervention\Image\Interfac
• Failed to invert color

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