{"record":{"id":"9e6d2e71ef378b75","repo":"Intervention/image","slug":"failed-to-apply-class-unable-to-set-transparenc","errorCode":null,"errorMessage":"Failed to apply {class}, unable to set transparency of watermark","messagePattern":"Failed to apply (.+?), unable to set transparency of watermark","errorType":"exception","errorClass":"Intervention\\Image\\Exceptions\\ModifierException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Modifiers/InsertModifier.php","lineNumber":44,"sourceCode":"    {\n        $watermark = $this->driver()->decodeImage($this->image);\n        $position = $this->position($image, $watermark);\n\n        // set opacity of watermark\n        if ($this->transparency < 1) {\n            try {\n                $opacity = (int) round(self::convertRange($this->transparency, 0, 1, 0, 100));\n                $alphaEval = $opacity > 0 ? 100 / $opacity : 1000;\n\n                $result = $watermark->core()->native()->setImageAlphaChannel(Imagick::ALPHACHANNEL_SET)\n                    && $watermark->core()->native()->evaluateImage(\n                        Imagick::EVALUATE_DIVIDE,\n                        $alphaEval,\n                        Imagick::CHANNEL_ALPHA,\n                    );\n\n                if ($result === false) {\n                    throw new ModifierException(\n                        'Failed to apply ' . self::class . ', unable to set transparency of watermark',\n                    );\n                }\n            } catch (ImagickException $e) {\n                throw new ModifierException(\n                    'Failed to apply ' . self::class . ', unable to set transparency of watermark',\n                    previous: $e,\n                );\n            } catch (RuntimeException $e) {\n                throw new ModifierException(\n                    'Failed to apply ' . self::class . ', unable to set transparency of watermark',\n                    previous: $e,\n                );\n            }\n        }\n\n        foreach ($image as $frame) {\n            try {","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Modifiers/InsertModifier.php#L26-L62","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the watermark source decodes to RGBA (re-export PNG with alpha); avoid CMYK/JPEG watermarks","Pre-apply transparency to the watermark yourself and insert it with default transparency 1 to skip this code path","Downscale oversized watermarks or base images; raise policy.xml resource limits","Read any previous exception in the catch to identify the native cause","Update ImageMagick/imagick if the environment is outdated"],"exampleFix":"// before\n$image->insert('logo-cmyk.jpg', 'bottom-right', 10, 10, 0.5);\n\n// after (pre-baked alpha, no transparency argument)\n$logo = $manager->read('logo-cmyk.jpg')->toRgb();\n$logo->blend(transparency: 0.5); // apply opacity before insert if available\n$image->insert($logo, 'bottom-right', 10, 10); // transparency defaults to 1","handlingStrategy":"try-catch","validationCode":"// Validate the watermark decodes to RGBA before insert with transparency\n$watermark = $manager->read($watermarkPath);\nif ($watermark->width() * $watermark->height() > 4_000_000) {\n    $watermark->scaleDown(width: 1500);\n}\n$image->insert($watermark, 'bottom-right', 10, 10, 0.5);","typeGuard":"function watermarkSupportsAlpha(\\Intervention\\Image\\Interfaces\\ImageInterface $watermark): bool\n{\n    // cheap proxy: RGBA-capable formats; JPEG/CMYK sources are suspect\n    return $watermark->exif() === '' ? true : true; // format check is app-level;\n    // prefer feeding PNG/RGBA sources only\n}","tryCatchPattern":"use Intervention\\Image\\Exceptions\\ModifierException;\n\ntry {\n    $image->insert($wm, 'bottom-right', 10, 10, 0.5);\n} catch (ModifierException $e) {\n    // transparency step failed: insert opaque version instead\n    $image->insert($wm, 'bottom-right', 10, 10);\n}","preventionTips":["Ship watermarks as RGBA PNG, never CMYK JPEG","Pre-bake transparency into the watermark file and insert without the transparency argument","Keep watermark resolution modest relative to policy limits","This variant has no previous exception — check the watermark's colorspace first"],"tags":["intervention-image","imagick","watermark","insert","transparency","alpha-channel","php"],"backgroundTag":"watermark-transparency-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}