Intervention/image · error · ModifierException

Failed to set image contrast

Error message

Failed to set image contrast

What it means

The GD driver applies contrast by calling imagefilter($gd, IMG_FILTER_CONTRAST, -$level) on every frame and throws this ModifierException as soon as imagefilter() returns false. The level itself is not the issue (any int is accepted); a false return means GD could not run the filter on that native GdImage at all. Frames decoded through the driver are always converted to truecolor first, so in a clean pipeline this path is practically unreachable - it signals corrupted native state or an image GD refuses to filter.

Source

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

use Intervention\Image\Interfaces\ImageInterface;
use Intervention\Image\Interfaces\SpecializedInterface;
use Intervention\Image\Modifiers\ContrastModifier as GenericContrastModifier;

class ContrastModifier extends GenericContrastModifier implements SpecializedInterface
{
    /**
     * {@inheritdoc}
     *
     * @see ModifierInterface::apply()
     *
     * @throws ModifierException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        foreach ($image as $frame) {
            $result = imagefilter($frame->native(), IMG_FILTER_CONTRAST, ($this->level * -1));
            if ($result === false) {
                throw new ModifierException('Failed to set image contrast');
            }
        }

        return $image;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Re-decode the image from its original source and apply contrast() to the fresh instance
2. If frames were turned into palette images (e.g. after reduceColors()), convert them back first: foreach ($image as $frame) { imagepalettetotruecolor($frame->native()); }
3. Verify the GD installation (php -i | grep -i gd, gd_info()) on the failing host
4. Catch ModifierException and skip the effect or fall back to a manual pixel loop

Example fix

// before: contrast applied to frames that are no longer filterable
$image->reduceColors(64)->contrast(30);

// after: return frames to truecolor before filtering
$image->reduceColors(64);
foreach ($image as $frame) {
    imagepalettetotruecolor($frame->native());
}
$image->contrast(30);

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->contrast(30);

use Intervention\Image\Exceptions\ModifierException;

try {
    $image->contrast(30);
} catch (ModifierException $e) {
    $logger?->warning('Contrast filter failed: ' . $e->getMessage());
    // keep the unmodified image
}

When it happens

Trigger: Calling $image->contrast($level) on frames whose native GdImage was replaced or invalidated by custom code (setNative() with a broken resource, manual imagedestroy(), hand-built Core objects); applying the filter to palette-based frames produced outside the normal decode path; the library's own test suite forcing imagefilter() to fail (testApplyThrowsWhenSpecializedWithoutOverride).

Common situations: Mixing raw GD resource manipulation with Intervention objects; long-lived workers that free GD resources while image objects survive; exotic or broken GD builds; unit tests deliberately exercising the failure branch.

Related errors

• Failed to apply Intervention\Image\Drivers\Gd\Modifiers\Gray
• 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/acef6951f3933c5d. Report an issue: GitHub.