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

Failed to apply {class}, unable to pixelate image

Error message

Failed to apply {class}, unable to pixelate image

What it means

pixelate() downscales each frame to roughly width/size and height/size (clamped to a 1-pixel minimum) and then scales it back up, producing blocky pixels. This exception fires when either of the two chained scaleImage() calls returns false, making the combined && expression false. The pixelation size itself is already validated (constructor rejects values < 1), so the failure comes from the native scaling step.

Source

Thrown at src/Drivers/Imagick/Modifiers/PixelateModifier.php:46

    /**
     * @throws ModifierException
     */
    protected function pixelateFrame(FrameInterface $frame): void
    {
        $size = $frame->size();

        try {
            $result = $frame->native()->scaleImage(
                (int) round(max(1, $size->width() / $this->size)),
                (int) round(max(1, $size->height() / $this->size)),
            ) && $frame->native()->scaleImage(
                $size->width(),
                $size->height(),
            );

            if ($result === false) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to pixelate image',
                );
            }
        } catch (ImagickException $e) {
            throw new ModifierException(
                'Failed to apply ' . self::class . ', unable to pixelate image',
                previous: $e,
            );
        } catch (DivisionByZeroError $e) {
            throw new ModifierException(
                'Failed to apply ' . self::class . ', unable to pixelate image',
                previous: $e,
            );
        }
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Inspect $e->getPrevious()?->getMessage() for the native reason (usually resource or policy wording)
2. Raise memory_limit or the policy.xml width/height/area limits so both scale stages can allocate
3. Pixelate a pre-downscaled copy and composite it back instead of pixelating the full-resolution frame
4. Reduce the pixelation size (larger blocks need the same allocations but a smaller intermediate) or process one frame at a time

Example fix

// before
$image->pixelate(20); // full-res frame, both scale stages unguarded

// after
use Intervention\Image\Exceptions\ModifierException;

try {
    $image->pixelate(20);
} catch (ModifierException $e) {
    $image->resize(1200, null)->pixelate(20); // fall back to smaller working size
}

use Intervention\Image\Exceptions\ModifierException;

try {
    $image->pixelate(20);
} catch (ModifierException $e) {
    $image->resize(1200, null)->pixelate(20); // degrade to smaller working size
}

When it happens

Trigger: $image->pixelate($size) where a scaleImage() stage returns false: downscaling to 1px then upscaling a very large frame trips resource/policy ceilings, or the frame data is unreadable.

Common situations: Generating pixelated previews of multi-megapixel photos on memory-constrained workers; hosts whose policy.xml caps width/height so the upscale-back stage is denied; pixelating frames of long GIF animations frame by frame.

Related errors

• Failed to apply {class}, unable to process resizing
• Failed to apply {class}, unable to rotate image
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers

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