What causes "Failed to apply {class}, unable to insert watermark image" in Intervention/image?

Downscale watermark or base image and retry to confirm a resource-limit cause

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

Failed to apply {class}, unable to insert watermark image

Error message

Failed to apply {class}, unable to insert watermark image

What it means

This ModifierException is thrown by $image->insert() when compositing the watermark onto the base image fails with a false return. For every frame the driver calls compositeImage($watermarkNative, Imagick::COMPOSITE_DEFAULT, $x, $y); a false return is reported as 'unable to insert watermark image' with no chained previous exception, meaning ImageMagick declined the composite in this environment.

Source

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

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

        foreach ($image as $frame) {
            try {
                $result = $frame->native()->compositeImage(
                    $watermark->core()->native(),
                    Imagick::COMPOSITE_DEFAULT,
                    $position->x(),
                    $position->y(),
                );
                if ($result === false) {
                    throw new ModifierException(
                        'Failed to apply ' . self::class . ', unable to insert watermark image',
                    );
                }
            } catch (ImagickException $e) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to insert watermark image',
                    previous: $e,
                );
            }
        }

        return $image;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

Downscale watermark or base image and retry to confirm a resource-limit cause
Inspect and raise width/height/area limits in /etc/ImageMagick-*/policy.xml
Re-encode suspicious base images or watermarks to clean PNG/JPEG
Update ImageMagick and the imagick extension
If the environment cannot be changed, perform insertion with the GD driver instead

Example fix

// before
$image->insert('huge-logo.png', 'center'); // 12000px logo, policy caps area

// after
$logo = $manager->read('huge-logo.png')->scaleDown(width: 2000);
$image->insert($logo, 'center');

Defensive patterns

Strategy: try-catch

Validate before calling

$watermark = $manager->read($watermarkPath);
if ($watermark->width() * $watermark->height() > 4_000_000) {
    $watermark->scaleDown(width: 2000);
}
$image->insert($watermark, 'center');

Try / catch

use Intervention\Image\Exceptions\ModifierException;

try {
    $image->insert($wm, 'center');
} catch (ModifierException $e) {
    Log::warning('Composite returned false: ' . optional($e->getPrevious())->getMessage());
    throw $e;
}

Prevention

Downscale watermarks and base images below policy.xml dimension/area caps
Re-encode untrusted sources before compositing
This variant has no previous exception — suspect resource limits first
Run `magick -list resource` on hosts where composites intermittently fail

When it happens

Trigger: Calling $image->insert($source, ...) with watermark dimensions exceeding ImageMagick's resource limits (policy.xml width/height/area caps); compositing onto corrupted frames; environments where the composite operation is policy-restricted; watermark/base combinations (e.g. extreme bit depths) unsupported by the installed build.

Common situations: Inserting large print-resolution watermarks on shared hosting; policy.xml capping dimensions below the asset sizes; batch pipelines processing truncated uploads; minimal Docker ImageMagick configurations.

Related errors

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