{"record":{"id":"b70e6329fcecbbcb","repo":"Intervention/image","slug":"failed-to-encode-heic-format","errorCode":null,"errorMessage":"Failed to encode heic format","messagePattern":"Failed to encode heic format","errorType":"exception","errorClass":"EncoderException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Encoders/HeicEncoder.php","lineNumber":49,"sourceCode":"\n        // strip meta data\n        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->setCompressionQuality($this->quality);\n            $imagick->setImageCompressionQuality($this->quality);\n\n            $result = new EncodedImage($imagick->getImagesBlob(), 'image/heic');\n            $imagick->clear();\n\n            return $result;\n        } catch (ImagickException | ImageException $e) {\n            throw new EncoderException('Failed to encode heic format', previous: $e);\n        }\n    }\n}\n","sourceCodeStart":31,"sourceCodeEnd":53,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Encoders/HeicEncoder.php#L31-L53","documentation":"The Imagick driver's HeicEncoder clones the native Imagick object, sets format 'HEIC' and the configured compression quality (src/Drivers/Imagick/Encoders/HeicEncoder.php:38-42), then serializes with getImagesBlob(). Any ImagickException or ImageException is rethrown as EncoderException ('Failed to encode heic format') with the original as previous. The dominant real-world cause is ImageMagick built without the libheif delegate - the previous exception then reads 'no encode delegate for this image format'. Check $e->getPrevious()->getMessage() before assuming a code bug.","triggerScenarios":"Calling toHeic() or encoding to a *.heic target on the Imagick driver when setFormat('HEIC')/setImageFormat('HEIC') throws because ImageMagick has no HEIF coder: php -r \"var_dump((new Imagick())->queryFormats('HEIC'));\" returns an empty array. Also triggered if getImagesBlob() fails mid-serialization in a partially capable build.","commonSituations":"Default php Docker images and most distro ImageMagick builds without libheif; ImageMagick 6 (no practical HEIC write support); shared hosting; staging servers where HEIC worked locally (Homebrew imagemagick with libheif) but not in production.","solutions":["Catch EncoderException and read $e->getPrevious()->getMessage() to confirm the delegate error.","Confirm capability with Imagick::queryFormats('HEIC') on the failing host - an empty array is definitive.","Install libheif (e.g. apt-get install libheif-dev on Debian/Ubuntu) plus an ImageMagick build linked against it, then rebuild the imagick extension.","In Docker, install imagemagick with libheif1 before pecl install imagick so the extension binds a HEIF-capable library.","If the environment cannot be changed, gate the feature: encode to JPEG/WebP instead, or handle HEIC upload conversion on the client/edge."],"exampleFix":"// before\n$encoded = $manager->read($request->file('photo'))->toHeic();\n\n// after\n$heicSupported = in_array('HEIC', Imagick::queryFormats('HEIC'), true);\n$encoded = $heicSupported\n    ? $manager->read($request->file('photo'))->toHeic()\n    : $manager->read($request->file('photo'))->toJpeg();","handlingStrategy":"validation","validationCode":"$heicSupported = in_array('HEIC', Imagick::queryFormats('HEIC'), true);\nif (!$heicSupported) {\n    throw new RuntimeException('HEIC encoding unavailable: ImageMagick lacks the libheif delegate');\n}\n$encoded = $image->toHeic();","typeGuard":null,"tryCatchPattern":"try {\n    $encoded = $image->toHeic();\n} catch (EncoderException $e) {\n    $reason = $e->getPrevious()?->getMessage() ?? $e->getMessage();\n    // typically: no encode delegate for this image format `HEIC'\n    $encoded = $image->toJpeg(); // degrade, then log $reason\n}","preventionTips":["Feature-detect HEIC at deploy time with Imagick::queryFormats('HEIC') and disable the option in UI/API when absent.","Ship identical Docker images to CI, staging and production so delegate availability never drifts.","If handling iPhone uploads, convert HEIC on the client or at the edge where a libheif-capable tool runs."],"tags":["heic","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"}