Intervention/image · error · ModifierException

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

Error message

Failed to apply Intervention\Image\Drivers\Gd\Modifiers\GrayscaleModifier, unable to transform image to grayscale

What it means

The GD driver converts each frame to grayscale with imagefilter($gd, IMG_FILTER_GRAYSCALE) and throws ModifierException when the call returns false. A driver-decoded frame is always a truecolor GdImage on which this filter succeeds, so a false return means the native image is not in a state GD can filter - an invalid or destroyed GdImage, or a frame converted to a palette image outside the normal pipeline. There are no parameters to get wrong: grayscale() takes none.

Source

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

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

class GrayscaleModifier extends GenericGrayscaleModifier implements SpecializedInterface
{
    /**
     * {@inheritdoc}
     *
     * @see ModifierInterface::apply()
     *
     * @throws ModifierException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        foreach ($image as $frame) {
            $result = imagefilter($frame->native(), IMG_FILTER_GRAYSCALE);
            if ($result === false) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to transform image to grayscale',
                );
            }
        }

        return $image;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Re-create the image from its source and apply grayscale() to the fresh instance
2. Ensure nothing destroyed or replaced frame natives (audit custom setNative()/imagedestroy() usage)
3. Convert palette frames back to truecolor: foreach ($image as $frame) { imagepalettetotruecolor($frame->native()); }
4. Catch ModifierException and skip the effect

Example fix

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

// after: decode fresh, normalize, then filter
$image = $manager->decode($sourceBinary);
foreach ($image as $frame) {
    if (!imageistruecolor($frame->native())) {
        imagepalettetotruecolor($frame->native());
    }
}
$image->grayscale();

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->grayscale();

use Intervention\Image\Exceptions\ModifierException;

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

When it happens

Trigger: $image->grayscale() after custom code invalidated frame natives (setNative() with a broken GdImage, manual imagedestroy()); filtering palette frames produced by hand-built cores; the library's test suite forcing imagefilter() to fail (testApplyThrowsWhenSpecializedWithoutOverride).

Common situations: Long-lived worker processes that keep image objects alive while raw GD resources were freed; raw GD interop layers; test doubles forcing imagefilter() to fail.

Related errors

• Failed to set image contrast
• Failed to invert image colors
• Failed to apply Intervention\Image\Drivers\Gd\Modifiers\Pixe
• Failed to apply Intervention\Image\Drivers\Gd\Modifiers\Blur
• Failed to apply Intervention\Image\Drivers\Gd\Modifiers\Brig

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