Intervention/image · error · EncoderException

Failed to encode webp format

Error message

Failed to encode webp format

What it means

Thrown by the Imagick WebP encoder when the cloned native Imagick object cannot accept a transparent background pixel before encoding. The ImagickPixelException from setImageBackgroundColor(new ImagickPixel('transparent')) at src/Drivers/Imagick/Encoders/WebpEncoder.php:48 is wrapped into an EncoderException with the original attached as previous. This is almost always an ImageMagick/imagick-extension environment problem (broken install, policy restrictions, exhausted memory), not a problem with your image data.

Source

Thrown at src/Drivers/Imagick/Encoders/WebpEncoder.php:50

     * @throws EncoderException
     */
    public function encode(ImageInterface $image): EncodedImageInterface
    {
        $format = 'WEBP';
        $compression = Imagick::COMPRESSION_ZIP;

        // strip meta data
        if ($this->strip || (is_null($this->strip) && $this->driver()->config()->strip)) {
            $image->modify(new StripMetaModifier());
        }

        try {
            $imagick = clone $image->core()->native();

            try {
                $imagick->setImageBackgroundColor(new ImagickPixel('transparent'));
            } catch (ImagickPixelException $e) {
                throw new EncoderException('Failed to encode webp format', previous: $e);
            }

            if (!$image->isAnimated()) {
                $merged = $imagick->mergeImageLayers(Imagick::LAYERMETHOD_MERGE);
                $imagick->clear();
                $imagick = $merged;
            }

            $imagick->setFormat($format);
            $imagick->setImageFormat($format);
            $imagick->setCompression($compression);
            $imagick->setImageCompression($compression);
            $imagick->setImageCompressionQuality($this->quality);

            if ($this->quality === 100) {
                $imagick->setOption('webp:lossless', 'true');
            }

View on GitHub (pinned to 5598b9e397)

Solutions

1. Check WEBP support: run Imagick::queryFormats('WEBP') — it must be non-empty
2. Rebuild the imagick extension against the installed ImageMagick (pecl install imagick) and restart PHP-FPM
3. Review /etc/ImageMagick-*/policy.xml for denied delegates or resource caps and re-enable webp
4. Raise PHP memory_limit and ImageMagick resource limits if the underlying error mentions allocation
5. If webp cannot be supported in this environment, encode a fallback format such as $image->toPng()

Example fix

// before
$data = $image->toWebp();

// after
if (!in_array('WEBP', Imagick::queryFormats(), true)) {
    throw new RuntimeException('WEBP delegate missing; cannot encode webp');
}
$data = $image->toWebp();

// Run before converting; fails fast if the environment cannot encode WEBP
if (!in_array('WEBP', Imagick::queryFormats(), true)) {
    throw new RuntimeException('ImageMagick lacks the WEBP delegate; cannot encode webp.');
}
$encoded = $image->toWebp();

use Intervention\Image\Exceptions\EncoderException;

try {
    $blob = $image->toWebp()->toDataPointer();
} catch (EncoderException $e) {
    $reason = $e->getPrevious()?->getMessage() ?? $e->getMessage();
    error_log('WebP encode failed: ' . $reason);
    $blob = $image->toPng()->toDataPointer(); // fallback format
}

When it happens

Trigger: Calling $image->toWebp(), $manager->write($image, 'webp'), or encoding to a .webp file/extension with the Imagick driver in an environment where constructing or applying the 'transparent' pixel fails: imagick PECL extension compiled against a different ImageMagick than the loaded one, policy.xml restrictions, or memory exhaustion inside the extension.

Common situations: Container images where imagick and ImageMagick versions drift apart after an apt/pecl upgrade; shared hosting with restrictive /etc/ImageMagick-*/policy.xml; low PHP memory_limit or MAGICK resource caps when encoding large images.

Related errors

• Failed to analyze colorspace
• Unable to read ImageMagick version number
• Failed query font metrics
• Failed to create instance of Intervention\Image\Drivers\Imag
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers

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