Intervention/image · error · ModifierException

Failed to apply…

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.

Solutions

Catch ModifierException and degrade gracefully (skip the effect or the file)
Confirm the source image decodes cleanly before applying modifiers
Clone to a fresh truecolor native and retry once
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]);
}

Defensive patterns

Strategy: try-catch

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Abort pipelines on earlier soft failures instead of continuing
Wrap effect application per image in batch jobs
Prefer fresh clones over reusing mutated natives

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

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

Appendix: 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)