Intervention/image · error · EncoderException

Failed to encode avif format

Error message

Failed to encode avif format

What it means

The Imagick driver's AvifEncoder converts the image to AVIF by cloning the native Imagick object, setting format 'AVIF' with COMPRESSION_ZIP and the configured quality (src/Drivers/Imagick/Encoders/AvifEncoder.php:40-46), then serializing with getImagesBlob(). Any ImagickException or ImageException thrown by those calls is rethrown as EncoderException ('Failed to encode avif format') with the original exception as previous. In practice the previous exception is almost always ImageMagick's 'no encode delegate for this image format', because AVIF output requires ImageMagick 7 built with libheif/libaom. Always inspect $e->getPrevious()->getMessage() for the real cause.

Source

Thrown at src/Drivers/Imagick/Encoders/AvifEncoder.php:53

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

        try {
            $imagick = clone $image->core()->native();
            $imagick->setFormat($format);
            $imagick->setImageFormat($format);
            $imagick->setCompression($compression);
            $imagick->setImageCompression($compression);
            $imagick->setCompressionQuality($this->quality);
            $imagick->setImageCompressionQuality($this->quality);

            $result = new EncodedImage($imagick->getImagesBlob(), 'image/avif');
            $imagick->clear();

            return $result;
        } catch (ImagickException | ImageException $e) {
            throw new EncoderException('Failed to encode avif format', previous: $e);
        }
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Catch EncoderException and read $e->getPrevious()->getMessage() - it names the exact ImageMagick failure (usually a missing delegate).
2. Run php -r "var_dump((new Imagick())->queryFormats('AVIF'));" - an empty array confirms ImageMagick cannot write AVIF on this host.
3. Install the delegate libraries (libheif, libaom) and an ImageMagick 7 build that links them, then rebuild the imagick PHP extension (pecl install imagick) so it picks up the new library.
4. In Docker, base the image on a variant that ships HEIF/AVIF-capable ImageMagick or apt-get install imagemagick with libheif1/libaom0 before installing the imagick extension.
5. If the delegate cannot be added (shared hosting), switch that operation to the GD driver (PHP 8.1+ with libgd AVIF support) or fall back to toWebp()/toJpeg().
6. Add a boot-time capability check (queryFormats) and disable the AVIF feature flag when unsupported, instead of failing per request.

Example fix

// before
$encoded = $manager->read('photo.png')->toAvif(); // EncoderException on hosts without the AVIF delegate

// after
$avifSupported = in_array('AVIF', Imagick::queryFormats('AVIF'), true);
$encoded = $avifSupported
    ? $manager->read('photo.png')->toAvif()
    : $manager->read('photo.png')->toWebp(); // graceful fallback

$avifSupported = in_array('AVIF', Imagick::queryFormats('AVIF'), true);
if (!$avifSupported) {
    throw new RuntimeException('AVIF encoding unavailable on this ImageMagick build');
}
$encoded = $image->toAvif();

try {
    $encoded = $image->toAvif();
} catch (EncoderException $e) {
    $reason = $e->getPrevious()?->getMessage() ?? $e->getMessage();
    // typically: no encode delegate for this image format `AVIF'
    $encoded = $image->toWebp(); // degrade, then log $reason
}

When it happens

Trigger: Calling toAvif(), encodeByExtension()/encodeByMime() on a *.avif target, or an AvifEncoder instance on the Imagick driver when the ImageMagick behind the imagick extension lacks AVIF support: setFormat('AVIF')/setImageFormat('AVIF') at AvifEncoder.php:41-42 throws, or getImagesBlob() fails. Quick reproduction check: php -r "var_dump((new Imagick())->queryFormats('AVIF'));" returning an empty array.

Common situations: Official php:8.x Docker images where imagick links against an ImageMagick without the AVIF delegate; ImageMagick 6 installations (AVIF needs IM7); shared hosting with a stock imagick build; macOS Homebrew imagemagick compiled without libheif; staging/CI environments that differ from production in delegate availability.

Related errors

• Failed to encode bmp format
• Failed to encode heic format
• Failed to encode jp2 format
• Failed to encode jxl format
• Failed to encode tiff format

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