Intervention/image · error · EncoderException

Failed to encode image to GIF format

Error message

Failed to encode image to GIF format

What it means

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.

Source

Thrown at src/Drivers/Gd/Encoders/GifEncoder.php:72

        try {
            $builder = GifBuilder::canvas(
                $image->width(),
                $image->height(),
            );

            foreach ($image as $frame) {
                $builder->addFrame(
                    source: $this->encode($frame->toImage($image->driver()))->toStream(),
                    delay: $frame->delay(),
                    interlaced: $this->interlaced,
                );
            }

            $builder->setLoops($image->loops());

            return new EncodedImage($builder->encode(), 'image/gif');
        } catch (GifException | FilesystemException $e) {
            throw new EncoderException('Failed to encode image to GIF format', previous: $e);
        }
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Ensure the temp directory (sys_get_temp_dir()) is writable and has free space; set TMPDIR if needed
2. Reduce frame count or resolution before encoding the animation
3. Catch EncoderException and inspect getPrevious() to distinguish GifException (frame data) from FilesystemException (disk/permissions)
4. Switch to the Imagick driver for animated GIF encoding if failures persist

Example fix

// before
$encoded = $image->toGif();

// after
try {
    $encoded = $image->toGif();
} catch (EncoderException $e) {
    if ($e->getPrevious() instanceof FilesystemException) {
        // temp dir full/unwritable: free space or point TMPDIR elsewhere
    }
    throw $e;
}

$dir = sys_get_temp_dir();
if (!is_writable($dir) || disk_free_space($dir) < 50 * 1024 * 1024) {
    throw new RuntimeException('Temp dir not writable or low on disk');
}

try {
    $encoded = $image->toGif();
} catch (EncoderException $e) {
    $cause = $e->getPrevious(); // GifException vs FilesystemException
    // fix temp dir/disk, reduce frames, or retry with Imagick driver
}

When it happens

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

Common situations: Animated GIFs with many large frames in constrained workers, containers with full or read-only /tmp, hardened PHP setups restricting writes outside the project.

Related errors

• The specified index is outside of the range
• Frame #${position} could not be found in the image
• Failed to decode GIF format
• Trim modifier cannot be applied to animated images
• Invalid $limit value. Must be int<1, max>

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