Intervention/image · error · ImageDecoderException

Failed to decode unsupported image format from binary data

Error message

Failed to decode unsupported image format from binary data

What it means

Core decode failure of the GD driver: imagecreatefromstring($input) returned false, meaning PHP's GD does not recognize the binary as any format it can parse (JPEG, PNG, GIF, WebP, BMP, XBM... depending on build). The data is not empty (that is checked earlier) and GIFs are diverted before this point, so this ImageDecoderException means 'bytes present, but not a decodable image' — unsupported format, corruption, or truncation.

Source

Thrown at src/Drivers/Gd/Decoders/BinaryImageDecoder.php:75

        return $this->isGifFormat($input) ? $this->decodeGif($input) : $this->decodeBinary($input);
    }

    /**
     * Decode image from given binary data
     *
     * @throws InvalidArgumentException
     * @throws ImageDecoderException
     * @throws DriverException
     * @throws StateException
     * @throws NotSupportedException
     */
    private function decodeBinary(string $input): ImageInterface
    {
        $gd = @imagecreatefromstring($input);

        if ($gd === false) {
            throw new ImageDecoderException('Failed to decode unsupported image format from binary data');
        }

        // create image instance
        $image = parent::decode($gd);

        // get media type
        $mediaType = $this->mediaTypeByBinary($input);

        // extract & set exif data for appropriate formats
        if (in_array($mediaType->format(), [Format::JPEG, Format::TIFF])) {
            $image->setExif($this->extractExifData($input));
        }

        // set mediaType on origin
        $image->origin()->setMediaType($mediaType);

        // adjust image orientation
        if ($this->driver()->config()->autoOrientation) {

View on GitHub (pinned to 5598b9e397)

Solutions

1. Determine what the bytes are: mime_content_type on a temp file, or check magic bytes (first 8-16 hex chars) against known signatures
2. If the file is valid but unsupported by GD (TIFF/HEIC/ICO/SVG), decode it with the Imagick driver or convert externally (ImageMagick, libvips) to PNG first
3. If the file should be a valid JPEG/PNG, re-download or re-export the original — verify size/checksum against the source
4. Verify GD capabilities: check gd_info() for WebP/AVIF support and rebuild/switch the PHP image if a needed codec is missing

Example fix

// before
$image = $manager->read(file_get_contents('/tmp/logo.svg'));
// ImageDecoderException: Failed to decode unsupported image format from binary data

// after (SVG is not raster-decodable; rasterize it first)
$png = shell_exec(sprintf('rsvg-convert --output-format=png %s', escapeshellarg('/tmp/logo.svg')));
$image = $manager->read($png);

if (@imagecreatefromstring($data) === false) {
    throw new RuntimeException('GD cannot decode this data (format unsupported, corrupt, or codec missing)');
}

try {
    $image = $manager->read($binary);
} catch (\Intervention\Image\Exceptions\ImageDecoderException $e) {
    // unsupported or corrupt image data; identify via magic bytes and reject
    $sig = bin2hex(substr($binary, 0, 8));
    logger()->info('Decode failed, signature: ' . $sig);
}

When it happens

Trigger: ImageManager::read($binary) with SVG markup, TIFF/HEIC/ICO bytes, a JPEG whose header was damaged, a PNG truncated mid-transfer, or a format this PHP-GD build lacks compiled support for. Also reached directly via decodeBinary in tests and via the Base64/DataUri decoders whose payloads end up here.

Common situations: User-uploaded SVGs (very common: read() on SVG bytes); HEIC photos from iPhones; ICO favicons; images passing through text-mode transfers that mangled bytes; PHP-GD compiled without WebP/AVIF so even valid files fail; random bytes from misrouted form fields.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Base64-encoded data contains unsupported image type
• Unsupported media type (MIME) ${mime}.
• File contains unsupported image format
• Failed to read media (MIME) type from binary data
• Data Uri contains unsupported image type

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