Intervention/image · error · Intervention\Image\Exceptions\DriverException

Failed to coalesce image

Error message

Failed to coalesce image

What it means

For every non-JPEG input the decoder calls coalesceImages() to expand animation frames into full-size representations; that call threw an ImagickException. Note this surfaces as DriverException (not ImageDecoderException), so unlike format errors it is never rewrapped by the higher decoders - it propagates as-is. Most common with animated GIF/WebP whose frame data is damaged, or when coalescing a large animation exhausts memory.

Source

Thrown at src/Drivers/Imagick/Decoders/NativeObjectDecoder.php:63

        if (!$input instanceof Imagick) {
            throw new InvalidArgumentException('Image source must be an instance of Imagick');
        }

        try {
            $originalMimeType = $input->getImageMimeType();
        } catch (ImagickException $e) {
            throw new ImageDecoderException('Failed to retrieve image media type', previous: $e);
        }

        // For some JPEG formats, the "coalesceImages()" call leads to an image
        // completely filled with background color. The logic behind this is
        // incomprehensible for me; could be an imagick bug.
        try {
            if ($input->getImageFormat() !== 'JPEG') {
                $input = $input->coalesceImages();
            }
        } catch (ImagickException $e) {
            throw new DriverException('Failed to coalesce image', previous: $e);
        }

        // turn images with colorspace 'GRAY' into 'SRGB' to avoid working on
        // grayscale colorspace images as this results images loosing color
        // information when placed into this image.
        try {
            if ($input->getImageColorspace() === Imagick::COLORSPACE_GRAY) {
                $input->setImageColorspace(Imagick::COLORSPACE_SRGB);
            }

            // AVIF/HEIF store their pixels in a luma/chroma (YCbCr) colorspace.
            // Recent ImageMagick normalizes this to sRGB on decode, but older
            // releases report the image as YCbCr, which leaves every later color
            // operation (colorspace analysis, pixel reads) working on raw
            // luma/chroma values. Convert it to sRGB so colors are correct.
            if ($input->getImageColorspace() === Imagick::COLORSPACE_YCBCR) {
                $input->transformImageColorspace(Imagick::COLORSPACE_SRGB);
            }

View on GitHub (pinned to 5598b9e397)

Solutions

1. Raise PHP memory_limit for the processing job (e.g. a queued worker with memory_limit=-1) and check ImageMagick's own caps with `convert -list resource`
2. Reproduce externally with `convert animation.gif -coalesce /tmp/out.gif` to get the native error message
3. Repair the animation's frame structure by re-encoding: gifsicle --unoptimize / re-save with ffmpeg or ImageMagick
4. If only one frame matters, extract it externally (convert 'in.gif[0]' frame.png) and read that still
5. If getPrevious() shows an internal ImageMagick error, upgrade ImageMagick

Example fix

// before
$image = $manager->read('broken-animation.gif'); // coalesceImages() fails

// after: repair/flatten the animation before decoding
exec('convert broken-animation.gif -coalesce repaired.gif');
$image = $manager->read('repaired.gif');

try {
    $image = $manager->read($path);
} catch (\Intervention\Image\Exceptions\DriverException $e) {
    // coalesceImages() failed (note: DriverException, not ImageDecoderException)
    $native = $e->getPrevious()?->getMessage() ?? 'unknown';
    $logger->warning('Coalesce failed: ' . $native);
    throw $e;
}

When it happens

Trigger: ImageManager::read() on an animated GIF/APNG/animated WebP with a corrupt frame; a 100+ frame animation whose coalesced full-size frames exceed PHP memory_limit or ImageMagick's policy.xml resource limits.

Common situations: User-uploaded animated stickers processed on servers with low memory_limit (128M); ImageMagick policy.xml capping memory/area; frames referencing broken disposal regions after a bad upload.

Related errors

• Failed to get image loop count
• Failed to set image loop count
• Failed to get frame disposal method
• Failed to set frame offset
• Failed to get frame offset

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