Intervention/image · error · ModifierException

Failed to apply colorize effect

Error message

Failed to apply colorize effect

What it means

ColorizeModifier applies IMG_FILTER_COLORIZE with red/green/blue values scaled to -255..255 for each frame and converts a false imagefilter() result into ModifierException. Like the other GD filter wrappers, a false return indicates the native could not be processed, not that the colorize values were wrong (they are pre-clamped by the scaling).

Source

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

{
    /**
     * {@inheritdoc}
     *
     * @see ModifierInterface::apply()
     *
     * @throws ModifierException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        // normalize colorize levels
        $red = (int) round($this->red * 2.55);
        $green = (int) round($this->green * 2.55);
        $blue = (int) round($this->blue * 2.55);

        foreach ($image as $frame) {
            $result = imagefilter($frame->native(), IMG_FILTER_COLORIZE, $red, $green, $blue);
            if ($result === false) {
                throw new ModifierException('Failed to apply colorize effect');
            }
        }

        return $image;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Catch ModifierException and skip or re-encode the affected image
2. Verify frame natives are valid GdImage instances before applying the modifier
3. Retry once on a freshly cloned truecolor copy
4. Switch to the Imagick driver for environments where GD misbehaves

Example fix

// before
$image->colorize(50, 0, -50);

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

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

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

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

When it happens

Trigger: ->colorize(r, g, b) on a degenerate or mocked GdImage native in test environments; images whose core became invalid after a prior partial failure.

Common situations: Automated test suites that force filter failure, batch pipelines continuing after an earlier soft failure corrupted frame natives.

Related errors

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

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