Intervention/image · error · ModifierException

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

Error message

Failed to apply Intervention\Image\Drivers\Gd\Modifiers\BrightnessModifier, unable to set image brightness

What it means

BrightnessModifier passes IMG_FILTER_BRIGHTNESS with the level scaled to -255..255 for each frame; imagefilter() returning false is converted into ModifierException. With a valid GdImage native this is practically unreachable and signals an unusable native rather than a bad level value.

Source

Thrown at src/Drivers/Gd/Modifiers/BrightnessModifier.php:31

{
    /**
     * {@inheritdoc}
     *
     * @see ModifierInterface::apply()
     *
     * @throws ModifierException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        foreach ($image as $frame) {
            $result = imagefilter(
                $frame->native(),
                IMG_FILTER_BRIGHTNESS,
                max(-255, min(255, intval($this->level * 2.55))),
            );

            if ($result === false) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to set image brightness',
                );
            }
        }

        return $image;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Catch ModifierException and degrade gracefully (skip the effect or the file)
2. Confirm the source image decodes cleanly before applying modifiers
3. Clone to a fresh truecolor native and retry once
4. Use the Imagick driver if a specific environment fails consistently

Example fix

// before
$image->brightness(50);

// after
try {
    $image->brightness(50);
} catch (ModifierException $e) {
    logs()->warning('brightness failed', ['file' => $fileId]);
}

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

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

try {
    $image->brightness(50);
} catch (ModifierException $e) {
    // log, skip effect, or retry on a cloned truecolor copy
}

When it happens

Trigger: ->brightness(x) applied to a degenerate GdImage native; mocked/specialized driver setups that make imagefilter() fail (testApplyThrowsWhenSpecializedWithoutOverride).

Common situations: CI runs with substitute driver classes, images manipulated after a partial earlier failure leaving the core in a bad state.

Related errors

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