Intervention/image · error · Intervention\Image\Exceptions\ModifierException

Failed to apply {class}, unable to set transparency of water

Error message

Failed to apply {class}, unable to set transparency of watermark

What it means

This ModifierException is thrown by $image->insert() when applying watermark transparency fails with a false return. When the transparency argument is below 1, the Imagick driver calls setImageAlphaChannel(Imagick::ALPHACHANNEL_SET) chained with evaluateImage(Imagick::EVALUATE_DIVIDE, $alphaEval, Imagick::CHANNEL_ALPHA); if the combined expression returns false, the driver reports 'unable to set transparency of watermark' with no chained previous exception.

Source

Thrown at src/Drivers/Imagick/Modifiers/InsertModifier.php:44

    {
        $watermark = $this->driver()->decodeImage($this->image);
        $position = $this->position($image, $watermark);

        // set opacity of watermark
        if ($this->transparency < 1) {
            try {
                $opacity = (int) round(self::convertRange($this->transparency, 0, 1, 0, 100));
                $alphaEval = $opacity > 0 ? 100 / $opacity : 1000;

                $result = $watermark->core()->native()->setImageAlphaChannel(Imagick::ALPHACHANNEL_SET)
                    && $watermark->core()->native()->evaluateImage(
                        Imagick::EVALUATE_DIVIDE,
                        $alphaEval,
                        Imagick::CHANNEL_ALPHA,
                    );

                if ($result === false) {
                    throw new ModifierException(
                        'Failed to apply ' . self::class . ', unable to set transparency of watermark',
                    );
                }
            } catch (ImagickException $e) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to set transparency of watermark',
                    previous: $e,
                );
            } catch (RuntimeException $e) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to set transparency of watermark',
                    previous: $e,
                );
            }
        }

        foreach ($image as $frame) {
            try {

View on GitHub (pinned to 5598b9e397)

Solutions

1. Verify the watermark source decodes to RGBA (re-export PNG with alpha); avoid CMYK/JPEG watermarks
2. Pre-apply transparency to the watermark yourself and insert it with default transparency 1 to skip this code path
3. Downscale oversized watermarks or base images; raise policy.xml resource limits
4. Read any previous exception in the catch to identify the native cause
5. Update ImageMagick/imagick if the environment is outdated

Example fix

// before
$image->insert('logo-cmyk.jpg', 'bottom-right', 10, 10, 0.5);

// after (pre-baked alpha, no transparency argument)
$logo = $manager->read('logo-cmyk.jpg')->toRgb();
$logo->blend(transparency: 0.5); // apply opacity before insert if available
$image->insert($logo, 'bottom-right', 10, 10); // transparency defaults to 1

// Validate the watermark decodes to RGBA before insert with transparency
$watermark = $manager->read($watermarkPath);
if ($watermark->width() * $watermark->height() > 4_000_000) {
    $watermark->scaleDown(width: 1500);
}
$image->insert($watermark, 'bottom-right', 10, 10, 0.5);

function watermarkSupportsAlpha(\Intervention\Image\Interfaces\ImageInterface $watermark): bool
{
    // cheap proxy: RGBA-capable formats; JPEG/CMYK sources are suspect
    return $watermark->exif() === '' ? true : true; // format check is app-level;
    // prefer feeding PNG/RGBA sources only
}

use Intervention\Image\Exceptions\ModifierException;

try {
    $image->insert($wm, 'bottom-right', 10, 10, 0.5);
} catch (ModifierException $e) {
    // transparency step failed: insert opaque version instead
    $image->insert($wm, 'bottom-right', 10, 10);
}

When it happens

Trigger: Calling $image->insert($watermarkSource, $position, $x, $y, 0.5) with a watermark in a format/colorspace that does not support the alpha-channel operations of the installed ImageMagick (e.g. CMYK JPEGs); very large watermarks exceeding resource limits; policy-restricted environments blocking channel evaluation.

Common situations: Watermarking with CMYK-encoded logo assets from print workflows; inserting high-resolution watermarks onto large base images on memory-limited hosts; shared hosting with restrictive policy.xml; minimal Docker ImageMagick installations.

Related errors

• Failed to apply {class}, unable to set image background colo
• Failed to apply {class}, unable to insert watermark image
• Color channel value of {class} must be in range 0 to 1
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Failed to build watermark image

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