{"record":{"id":"886d8f2ef9c4f97a","repo":"Intervention/image","slug":"failed-to-build-watermark","errorCode":null,"errorMessage":"Failed to build watermark","messagePattern":"Failed to build watermark","errorType":"exception","errorClass":"ModifierException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Modifiers/InsertModifier.php","lineNumber":59,"sourceCode":"            );\n        }\n\n        return $image;\n    }\n\n    /**\n     * Build watermark image.\n     *\n     * @throws ModifierException\n     */\n    private function watermark(): ImageInterface\n    {\n        try {\n            $watermark = $this->driver()->decodeImage($this->image);\n\n            return $this->transparency === 1.0 ? $watermark : $this->fadeWatermark($watermark);\n        } catch (ImageException $e) {\n            throw new ModifierException('Failed to build watermark', previous: $e);\n        }\n    }\n\n    /**\n     * Build a faded copy of the watermark by scaling each pixel's alpha\n     * by the requested transparency factor of the modifier. Created once\n     * and reused for every frame.\n     *\n     * @throws ModifierException\n     */\n    private function fadeWatermark(ImageInterface $watermark): ImageInterface\n    {\n        $width = $watermark->width();\n        $height = $watermark->height();\n\n        $faded = imagecreatetruecolor($width, $height);\n\n        if ($faded === false) {","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Modifiers/InsertModifier.php#L41-L77","documentation":"Before compositing, InsertModifier::watermark() decodes the watermark source through the driver pipeline (driver()->decodeImage($this->image)). Any ImageException raised there - missing or unreadable file, corrupt or truncated data, unsupported source type, missing GD format support - is wrapped into ModifierException 'Failed to build watermark' with the original cause available via getPrevious(). This is the most commonly hit insert() failure.","triggerScenarios":"$image->insert('watermark.png') with a wrong path or a path relative to a different working directory; passing an empty string, null or garbage binary; using a truncated/corrupt uploaded logo; WebP/AVIF watermarks without corresponding GD support; remote URLs when allow_url_fopen is off; passing a Laravel Storage::path() for a non-local disk.","commonSituations":"Watermark paths from env/config files that differ between environments; queue workers with a different cwd than web requests; user-supplied logos; shared hosts with partial GD format support.","solutions":["Verify the watermark exists and is a readable image before inserting: is_file(), is_readable(), getimagesize()","Pass binary contents (file_get_contents(), Storage::disk()->get()) or an already-decoded ImageInterface instead of a fragile path","Inspect $e->getPrevious() to find the real decoder error (FileNotFoundException, ImageDecoderException, ...)","Enable the required GD format (webp/avif) or convert the watermark to PNG/JPEG"],"exampleFix":"// before\n$image->insert(config('services.watermark.path'));\n\n// after\n$path = (string) config('services.watermark.path');\nif (!is_file($path) || !is_readable($path)) {\n    throw new RuntimeException('Watermark file missing or unreadable: ' . $path);\n}\n$image->insert(file_get_contents($path));","handlingStrategy":"validation","validationCode":"$path = 'watermarks/logo.png';\n\nif (is_string($path)) {\n    if (!is_file($path) || !is_readable($path)) {\n        throw new RuntimeException('Watermark file missing or unreadable: ' . $path);\n    }\n    if (getimagesize($path) === false) {\n        throw new RuntimeException('Watermark is not a valid image: ' . $path);\n    }\n}\n\n$image->insert(is_string($path) ? file_get_contents($path) : $path);","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\ModifierException;\n\ntry {\n    $image->insert($watermark);\n} catch (ModifierException $e) {\n    $reason = $e->getPrevious()?->getMessage() ?? $e->getMessage();\n    $logger->error('Watermark insert failed: ' . $reason);\n    // proceed without watermark\n}","preventionTips":["Validate watermark paths at boot (config check) rather than per request.","Pass binary strings or decoded ImageInterface objects instead of paths in queue workers.","Use absolute paths or resolve paths relative to a known root.","Verify GD has the format support your watermark files need (gd_info())."],"tags":["gd","insert","watermark","decode","file-io"],"backgroundTag":"image-decode-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}