Intervention/image · error · ModifierException

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

Error message

Failed to apply Intervention\Image\Drivers\Gd\Modifiers\BlurModifier, unable to process blur effect

What it means

The blur modifier runs IMG_FILTER_GAUSSIAN_BLUR via imagefilter() once per level per frame; a false return is wrapped in ModifierException. GD returns false only when the filter cannot be applied to the given native, which for a valid truecolor GdImage essentially never happens.

Source

Thrown at src/Drivers/Gd/Modifiers/BlurModifier.php:27

use Intervention\Image\Interfaces\SpecializedInterface;
use Intervention\Image\Modifiers\BlurModifier as GenericBlurModifier;

class BlurModifier extends GenericBlurModifier implements SpecializedInterface
{
    /**
     * {@inheritdoc}
     *
     * @see ModifierInterface::apply()
     *
     * @throws ModifierException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        foreach ($image as $frame) {
            for ($i = 0; $i < $this->level; $i++) {
                $result = imagefilter($frame->native(), IMG_FILTER_GAUSSIAN_BLUR);
                if ($result === false) {
                    throw new ModifierException(
                        'Failed to apply ' . self::class . ', unable to process blur effect',
                    );
                }
            }
        }

        return $image;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Catch ModifierException and fail that single image gracefully instead of the batch
2. Verify the image decoded cleanly (no fallback/partial state) before modifiers
3. Re-encode or clone to a fresh truecolor native before blurring
4. Try the Imagick driver for consistent filter behavior across environments

Example fix

// before
$image->blur(15);

// after
try {
    $image->blur(15);
} catch (ModifierException $e) {
    logs()->warning('blur failed', ['file' => $fileId]);
    // ship unblurred variant or re-encode
}

foreach ($image as $frame) {
    if (!$frame->native() instanceof GdImage) {
        throw new RuntimeException('Invalid frame native');
    }
}
$image->blur(15);

function isGdImage(mixed $value): bool
{
    return $value instanceof GdImage;
}

try {
    $image->blur(15);
} catch (ModifierException $e) {
    // log and ship unblurred variant, or re-encode to fresh truecolor and retry once
}

When it happens

Trigger: Applying ->blur(n) to a frame whose native is a degenerate or invalid GdImage (e.g. zero-sized or previously failed allocation); test environments that substitute or mock natives (testApplyThrowsWhenSpecializedWithoutOverride).

Common situations: Test/CI suites with specialized driver subclasses, images that slipped through a partially failed pipeline leaving broken natives, exotic or broken GD builds.

Related errors

• Failed to apply Intervention\Image\Drivers\Gd\Modifiers\Brig
• Failed to apply colorize effect
• Class '{objectShortname}' is not supported by {id} driver
• Failed to set image contrast
• Failed to apply Intervention\Image\Drivers\Gd\Modifiers\Gray

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