{"record":{"id":"f91a65abf0dd9b4e","repo":"Intervention/image","slug":"failed-to-encode-image-to-gif-format","errorCode":null,"errorMessage":"Failed to encode image to GIF format","messagePattern":"Failed to encode image to GIF format","errorType":"exception","errorClass":"EncoderException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Encoders/GifEncoder.php","lineNumber":72,"sourceCode":"        try {\n            $builder = GifBuilder::canvas(\n                $image->width(),\n                $image->height(),\n            );\n\n            foreach ($image as $frame) {\n                $builder->addFrame(\n                    source: $this->encode($frame->toImage($image->driver()))->toStream(),\n                    delay: $frame->delay(),\n                    interlaced: $this->interlaced,\n                );\n            }\n\n            $builder->setLoops($image->loops());\n\n            return new EncodedImage($builder->encode(), 'image/gif');\n        } catch (GifException | FilesystemException $e) {\n            throw new EncoderException('Failed to encode image to GIF format', previous: $e);\n        }\n    }\n}\n","sourceCodeStart":54,"sourceCodeEnd":76,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Encoders/GifEncoder.php#L54-L76","documentation":"When encoding an animated image to GIF, the GD driver rebuilds the animation through the intervention/gif builder, which also writes temporary files; any GifException or FilesystemException from that phase is wrapped in this EncoderException with the original as previous.","triggerScenarios":"$image->toGif() on an animated image where the builder cannot assemble frames (malformed frame data), or the filesystem layer fails (temp directory not writable, disk full, open_basedir restriction).","commonSituations":"Animated GIFs with many large frames in constrained workers, containers with full or read-only /tmp, hardened PHP setups restricting writes outside the project.","solutions":["Ensure the temp directory (sys_get_temp_dir()) is writable and has free space; set TMPDIR if needed","Reduce frame count or resolution before encoding the animation","Catch EncoderException and inspect getPrevious() to distinguish GifException (frame data) from FilesystemException (disk/permissions)","Switch to the Imagick driver for animated GIF encoding if failures persist"],"exampleFix":"// before\n$encoded = $image->toGif();\n\n// after\ntry {\n    $encoded = $image->toGif();\n} catch (EncoderException $e) {\n    if ($e->getPrevious() instanceof FilesystemException) {\n        // temp dir full/unwritable: free space or point TMPDIR elsewhere\n    }\n    throw $e;\n}","handlingStrategy":"try-catch","validationCode":"$dir = sys_get_temp_dir();\nif (!is_writable($dir) || disk_free_space($dir) < 50 * 1024 * 1024) {\n    throw new RuntimeException('Temp dir not writable or low on disk');\n}","typeGuard":null,"tryCatchPattern":"try {\n    $encoded = $image->toGif();\n} catch (EncoderException $e) {\n    $cause = $e->getPrevious(); // GifException vs FilesystemException\n    // fix temp dir/disk, reduce frames, or retry with Imagick driver\n}","preventionTips":["Monitor free space in the temp directory in production","Set TMPDIR explicitly in containers","Limit animated-GIF frame counts/resolution before encoding"],"tags":["gif","encoding","temp-dir","filesystem","gd"],"backgroundTag":"image-encode-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}