{"record":{"id":"d0dc650841a2ee4f","repo":"Intervention/image","slug":"failed-to-coalesce-image","errorCode":null,"errorMessage":"Failed to coalesce image","messagePattern":"Failed to coalesce image","errorType":"exception","errorClass":"Intervention\\Image\\Exceptions\\DriverException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Decoders/NativeObjectDecoder.php","lineNumber":63,"sourceCode":"        if (!$input instanceof Imagick) {\n            throw new InvalidArgumentException('Image source must be an instance of Imagick');\n        }\n\n        try {\n            $originalMimeType = $input->getImageMimeType();\n        } catch (ImagickException $e) {\n            throw new ImageDecoderException('Failed to retrieve image media type', previous: $e);\n        }\n\n        // For some JPEG formats, the \"coalesceImages()\" call leads to an image\n        // completely filled with background color. The logic behind this is\n        // incomprehensible for me; could be an imagick bug.\n        try {\n            if ($input->getImageFormat() !== 'JPEG') {\n                $input = $input->coalesceImages();\n            }\n        } catch (ImagickException $e) {\n            throw new DriverException('Failed to coalesce image', previous: $e);\n        }\n\n        // turn images with colorspace 'GRAY' into 'SRGB' to avoid working on\n        // grayscale colorspace images as this results images loosing color\n        // information when placed into this image.\n        try {\n            if ($input->getImageColorspace() === Imagick::COLORSPACE_GRAY) {\n                $input->setImageColorspace(Imagick::COLORSPACE_SRGB);\n            }\n\n            // AVIF/HEIF store their pixels in a luma/chroma (YCbCr) colorspace.\n            // Recent ImageMagick normalizes this to sRGB on decode, but older\n            // releases report the image as YCbCr, which leaves every later color\n            // operation (colorspace analysis, pixel reads) working on raw\n            // luma/chroma values. Convert it to sRGB so colors are correct.\n            if ($input->getImageColorspace() === Imagick::COLORSPACE_YCBCR) {\n                $input->transformImageColorspace(Imagick::COLORSPACE_SRGB);\n            }","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Decoders/NativeObjectDecoder.php#L45-L81","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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`","Reproduce externally with `convert animation.gif -coalesce /tmp/out.gif` to get the native error message","Repair the animation's frame structure by re-encoding: gifsicle --unoptimize / re-save with ffmpeg or ImageMagick","If only one frame matters, extract it externally (convert 'in.gif[0]' frame.png) and read that still","If getPrevious() shows an internal ImageMagick error, upgrade ImageMagick"],"exampleFix":"// before\n$image = $manager->read('broken-animation.gif'); // coalesceImages() fails\n\n// after: repair/flatten the animation before decoding\nexec('convert broken-animation.gif -coalesce repaired.gif');\n$image = $manager->read('repaired.gif');","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    $image = $manager->read($path);\n} catch (\\Intervention\\Image\\Exceptions\\DriverException $e) {\n    // coalesceImages() failed (note: DriverException, not ImageDecoderException)\n    $native = $e->getPrevious()?->getMessage() ?? 'unknown';\n    $logger->warning('Coalesce failed: ' . $native);\n    throw $e;\n}","preventionTips":["Size-limit animated uploads (frames and bytes) at the API boundary","Run animation processing in a worker with raised memory_limit","Pre-validate animations with `identify` or re-encode uploads through gifsicle/ffmpeg before storage"],"tags":["imagick","animation","gif","memory","coalesce"],"backgroundTag":"animated-image-processing-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}