Intervention/image · error · EncoderException

Failed to encode heic format

Error message

Failed to encode heic format

What it means

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.

Source

Thrown at src/Drivers/Imagick/Encoders/HeicEncoder.php:49

        // strip meta data
        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->setCompressionQuality($this->quality);
            $imagick->setImageCompressionQuality($this->quality);

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

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

View on GitHub (pinned to 5598b9e397)

Solutions

1. Catch EncoderException and read $e->getPrevious()->getMessage() to confirm the delegate error.
2. Confirm capability with Imagick::queryFormats('HEIC') on the failing host - an empty array is definitive.
3. Install libheif (e.g. apt-get install libheif-dev on Debian/Ubuntu) plus an ImageMagick build linked against it, then rebuild the imagick extension.
4. In Docker, install imagemagick with libheif1 before pecl install imagick so the extension binds a HEIF-capable library.
5. If the environment cannot be changed, gate the feature: encode to JPEG/WebP instead, or handle HEIC upload conversion on the client/edge.

Example fix

// before
$encoded = $manager->read($request->file('photo'))->toHeic();

// after
$heicSupported = in_array('HEIC', Imagick::queryFormats('HEIC'), true);
$encoded = $heicSupported
    ? $manager->read($request->file('photo'))->toHeic()
    : $manager->read($request->file('photo'))->toJpeg();

$heicSupported = in_array('HEIC', Imagick::queryFormats('HEIC'), true);
if (!$heicSupported) {
    throw new RuntimeException('HEIC encoding unavailable: ImageMagick lacks the libheif delegate');
}
$encoded = $image->toHeic();

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to encode avif format
• Failed to encode bmp 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/b70e6329fcecbbcb. Report an issue: GitHub.