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

Failed to apply {class}, unable to modulate image

Error message

Failed to apply {class}, unable to modulate image

What it means

This ModifierException is thrown by $image->grayscale() when the native color-desaturation call reports failure by returning false. The Imagick driver desaturates via modulateImage(100, 0, 100) on every frame; a false return is converted to 'unable to modulate image' with no chained previous exception, meaning ImageMagick declined or failed the modulation in this environment.

Source

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

use ImagickException;
use Intervention\Image\Exceptions\ModifierException;
use Intervention\Image\Interfaces\ImageInterface;
use Intervention\Image\Interfaces\SpecializedInterface;
use Intervention\Image\Modifiers\GrayscaleModifier as GenericGrayscaleModifier;

class GrayscaleModifier extends GenericGrayscaleModifier implements SpecializedInterface
{
    /**
     * @throws ModifierException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        foreach ($image as $frame) {
            try {
                $result = $frame->native()->modulateImage(100, 0, 100);
                if ($result === false) {
                    throw new ModifierException(
                        'Failed to apply ' . self::class . ', unable to modulate image',
                    );
                }
            } catch (ImagickException $e) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to modulate image',
                    previous: $e,
                );
            }
        }

        return $image;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Retry on a downscaled copy to confirm resource limits as the cause
2. Check and raise ImageMagick resource limits in policy.xml (`magick -list resource` to inspect)
3. Increase PHP memory_limit for large frames
4. Re-encode suspicious sources before processing
5. Update ImageMagick and the imagick extension to current versions

Example fix

// before
foreach ($uploads as $path) {
    $manager->read($path)->grayscale(); // fails on 80MP images
}

// after
foreach ($uploads as $path) {
    $image = $manager->read($path);
    if ($image->width() * $image->height() > 40_000_000) {
        $image->scaleDown(width: 5000);
    }
    $image->grayscale();
}

$pixelCount = $image->width() * $image->height();
if ($pixelCount > 40_000_000) {
    $image->scaleDown(width: 5000);
}
$image->grayscale();

use Intervention\Image\Exceptions\ModifierException;

try {
    $image->grayscale();
} catch (ModifierException $e) {
    Log::warning('Grayscale failed: ' . optional($e->getPrevious())->getMessage());
    throw $e;
}

When it happens

Trigger: Calling $image->grayscale() on very large images whose frames exceed ImageMagick's configured resource limits; desaturating frames with corrupted pixel caches; environments whose policy.xml restricts channel modulation operations.

Common situations: Batch grayscale conversion of high-resolution uploads on memory-limited hosts; processing truncated files that decode but cannot be modulated; Docker/minimal ImageMagick builds; policy-restricted shared hosting.

Related errors

• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Failed to apply {class}, unable to mirror image
• Failed to apply {class}, unable to insert watermark image
• Failed to import color {color_class} to {colorspace_class}

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