{"record":{"id":"014b95962b1579fc","repo":"Intervention/image","slug":"failed-to-encode-avif-format","errorCode":null,"errorMessage":"Failed to encode avif format","messagePattern":"Failed to encode avif format","errorType":"exception","errorClass":"EncoderException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Encoders/AvifEncoder.php","lineNumber":53,"sourceCode":"        if ($this->strip || (is_null($this->strip) && $this->driver()->config()->strip)) {\n            $image->modify(new StripMetaModifier());\n        }\n\n        try {\n            $imagick = clone $image->core()->native();\n            $imagick->setFormat($format);\n            $imagick->setImageFormat($format);\n            $imagick->setCompression($compression);\n            $imagick->setImageCompression($compression);\n            $imagick->setCompressionQuality($this->quality);\n            $imagick->setImageCompressionQuality($this->quality);\n\n            $result = new EncodedImage($imagick->getImagesBlob(), 'image/avif');\n            $imagick->clear();\n\n            return $result;\n        } catch (ImagickException | ImageException $e) {\n            throw new EncoderException('Failed to encode avif format', previous: $e);\n        }\n    }\n}\n","sourceCodeStart":35,"sourceCodeEnd":57,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Encoders/AvifEncoder.php#L35-L57","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Catch EncoderException and read $e->getPrevious()->getMessage() - it names the exact ImageMagick failure (usually a missing delegate).","Run php -r \"var_dump((new Imagick())->queryFormats('AVIF'));\" - an empty array confirms ImageMagick cannot write AVIF on this host.","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.","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.","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().","Add a boot-time capability check (queryFormats) and disable the AVIF feature flag when unsupported, instead of failing per request."],"exampleFix":"// before\n$encoded = $manager->read('photo.png')->toAvif(); // EncoderException on hosts without the AVIF delegate\n\n// after\n$avifSupported = in_array('AVIF', Imagick::queryFormats('AVIF'), true);\n$encoded = $avifSupported\n    ? $manager->read('photo.png')->toAvif()\n    : $manager->read('photo.png')->toWebp(); // graceful fallback","handlingStrategy":"validation","validationCode":"$avifSupported = in_array('AVIF', Imagick::queryFormats('AVIF'), true);\nif (!$avifSupported) {\n    throw new RuntimeException('AVIF encoding unavailable on this ImageMagick build');\n}\n$encoded = $image->toAvif();","typeGuard":null,"tryCatchPattern":"try {\n    $encoded = $image->toAvif();\n} catch (EncoderException $e) {\n    $reason = $e->getPrevious()?->getMessage() ?? $e->getMessage();\n    // typically: no encode delegate for this image format `AVIF'\n    $encoded = $image->toWebp(); // degrade, then log $reason\n}","preventionTips":["Run Imagick::queryFormats() checks in a boot/health check and expose codec availability as feature flags.","Bake delegate libraries (libheif, libaom) into the production Docker image and run CI on the same image.","Never assume a format supported locally is supported in production; encode tests are cheap.","Always log $e->getPrevious() when catching EncoderException - the outer message hides the ImageMagick cause."],"tags":["avif","imagick","encode","delegate","image-format"],"backgroundTag":"imagick-no-encode-delegate","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}