Intervention/image · error · ModifierException

Failed to apply Intervention\Image\Drivers\Gd\Modifiers\Pixe

Error message

Failed to apply Intervention\Image\Drivers\Gd\Modifiers\PixelateModifier, unable to process pixelation effect

What it means

The GD driver applies pixelation with imagefilter($gd, IMG_FILTER_PIXELATE, $size, true) per frame and throws ModifierException when the call returns false. The block size is passed straight to GD and is not what fails here; a false return means GD could not run the filter on the native image - an invalid/destroyed GdImage or a frame in a state GD refuses to filter (e.g. palette frames produced outside the normal decode path).

Source

Thrown at src/Drivers/Gd/Modifiers/PixelateModifier.php:26

use Intervention\Image\Interfaces\ImageInterface;
use Intervention\Image\Interfaces\SpecializedInterface;
use Intervention\Image\Modifiers\PixelateModifier as GenericPixelateModifier;

class PixelateModifier extends GenericPixelateModifier implements SpecializedInterface
{
    /**
     * {@inheritdoc}
     *
     * @see ModifierInterface::apply()
     *
     * @throws ModifierException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        foreach ($image as $frame) {
            $result = imagefilter($frame->native(), IMG_FILTER_PIXELATE, $this->size, true);
            if ($result === false) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to process pixelation effect',
                );
            }
        }

        return $image;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

Re-decode the image from source and apply pixelate() on the fresh instance
Audit custom setNative()/imagedestroy() usage that corrupts frame state
Convert palette frames back to truecolor: foreach ($image as $frame) { imagepalettetotruecolor($frame->native()); }
Catch ModifierException and skip the effect

Example fix

// before: pixelate on possibly corrupted native frames
$image->pixelate(10);

// after: decode fresh and normalize before filtering
$image = $manager->decode($sourceBinary);
foreach ($image as $frame) {
    if (!imageistruecolor($frame->native())) {
        imagepalettetotruecolor($frame->native());
    }
}
$image->pixelate(10);

Defensive patterns

Strategy: try-catch

Validate before calling

foreach ($image as $frame) {
    $native = $frame->native();
    if (!$native instanceof GdImage || imagesx($native) < 1) {
        throw new RuntimeException('Frame native is not a usable GdImage');
    }
    if (!imageistruecolor($native)) {
        imagepalettetotruecolor($native);
    }
}

$image->pixelate(10);

Try / catch

use Intervention\Image\Exceptions\ModifierException;

try {
    $image->pixelate(10);
} catch (ModifierException $e) {
    $logger?->warning('Pixelate filter failed: ' . $e->getMessage());
}

Prevention

Keep native frames untouched between modifier calls.
Normalize palette frames to truecolor before GD filters.
Verify GD builds on deployment targets with gd_info().

When it happens

Trigger: $image->pixelate($size) on frames whose native was replaced or invalidated by custom code; filtering palette-based frames from hand-built cores; the library's test suite forcing imagefilter() to fail (testApplyThrowsWhenSpecializedWithoutOverride).

Common situations: Raw GD interop layers; long-running workers where underlying resources were freed; test doubles exercising the failure branch.

Related errors

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