Intervention/image · error · ImageDecoderException

File contains unsupported image format

Error message

File contains unsupported image format

What it means

Top-level guard of FilePathImageDecoder::decode: after the path was confirmed readable, every failure of mediaTypeByFilePath (finfo MIME not in the MediaType enum, or both finfo and getimagesize failing on the content) is caught as Throwable and re-thrown as this generic ImageDecoderException. It therefore means 'the readable file at this path is not a recognized/decodable image' while masking the more specific cause from the caller.

Source

Thrown at src/Drivers/Gd/Decoders/FilePathImageDecoder.php:59

     *
     * @throws InvalidArgumentException
     * @throws ImageDecoderException
     * @throws DriverException
     * @throws StateException
     * @throws FileNotFoundException
     * @throws FileNotReadableException
     * @throws DirectoryNotFoundException
     */
    public function decode(mixed $input): ImageInterface
    {
        // make sure path is valid
        $path = self::readableFilePathOrFail($input);

        try {
            // detect media (mime) type
            $mediaType = $this->mediaTypeByFilePath($path);
        } catch (Throwable) {
            throw new ImageDecoderException('File contains unsupported image format');
        }

        $image = match ($mediaType->format()) {
            // gif files might be animated and therefore cannot
            // be handled by the standard GD decoder.
            Format::GIF => $this->decodeGif($path),
            default => $this->decodeDefault($path, $mediaType),
        };

        // set file path & mediaType on origin
        $image->origin()->setFilePath($path);
        $image->origin()->setMediaType($mediaType);

        // extract exif for the appropriate formats
        if ($mediaType->format() === Format::JPEG) {
            $image->setExif($this->extractExifData($path));
        }

View on GitHub (pinned to 5598b9e397)

Solutions

1. Diagnose outside the library: run file -b / mime_content_type on the exact path to see the real content type and compare with the MediaType enum
2. Convert or re-export the file to a mainstream raster format (PNG/JPEG/WebP) and retry
3. For TIFF/HEIC/ICO/JP2 content use the Imagick driver, which both maps and decodes those formats
4. Validate uploads by sniffed MIME (finfo) against a whitelist before saving/reading, not just by extension

Example fix

// before
$image = $manager->read($storedPath); // file is actually SVG named badge.png
// ImageDecoderException: File contains unsupported image format

// after
$mime = mime_content_type($storedPath);
if (!in_array($mime, ['image/jpeg','image/png','image/gif','image/webp','image/avif','image/bmp'], true)) {
    unlink($storedPath);
    throw new RuntimeException('Rejected non-image or unsupported file, detected as ' . $mime);
}
$image = $manager->read($storedPath);

$mime = mime_content_type($path);
$gdReadable = ['image/jpeg','image/png','image/gif','image/webp','image/avif','image/bmp'];
if (!in_array($mime, $gdReadable, true)) {
    throw new RuntimeException('File not readable as a GD-supported image, detected: ' . $mime);
}

try {
    $image = $manager->read($path);
} catch (\Intervention\Image\Exceptions\ImageDecoderException $e) {
    // generic wrapper: re-diagnose with mime_content_type() to find the real cause
    $mime = mime_content_type($path);
}

When it happens

Trigger: ImageManager::read('/path/to/file') with: an SVG or PDF; a text/binary file with a spoofed .jpg extension; a zero-byte or truncated image; camera-raw formats; files whose finfo MIME (e.g. image/x-targa, image/vnd.wap.wbmp) has no MediaType case. The inner NotSupportedException/ImageDecoderException from [120]/[122] is swallowed into this message.

Common situations: Upload validation that only checked extension; users renaming files; antivirus-mangled files; files on network mounts read partially; media libraries scanning directories and hitting mixed content; the catch-all hiding whether detection failed vs unsupported MIME, which confuses debugging.

Related errors

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

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