{"record":{"id":"813f5c545687836f","repo":"Intervention/image","slug":"file-contains-unsupported-image-format","errorCode":null,"errorMessage":"File contains unsupported image format","messagePattern":"File contains unsupported image format","errorType":"exception","errorClass":"ImageDecoderException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Decoders/FilePathImageDecoder.php","lineNumber":59,"sourceCode":"     *\n     * @throws InvalidArgumentException\n     * @throws ImageDecoderException\n     * @throws DriverException\n     * @throws StateException\n     * @throws FileNotFoundException\n     * @throws FileNotReadableException\n     * @throws DirectoryNotFoundException\n     */\n    public function decode(mixed $input): ImageInterface\n    {\n        // make sure path is valid\n        $path = self::readableFilePathOrFail($input);\n\n        try {\n            // detect media (mime) type\n            $mediaType = $this->mediaTypeByFilePath($path);\n        } catch (Throwable) {\n            throw new ImageDecoderException('File contains unsupported image format');\n        }\n\n        $image = match ($mediaType->format()) {\n            // gif files might be animated and therefore cannot\n            // be handled by the standard GD decoder.\n            Format::GIF => $this->decodeGif($path),\n            default => $this->decodeDefault($path, $mediaType),\n        };\n\n        // set file path & mediaType on origin\n        $image->origin()->setFilePath($path);\n        $image->origin()->setMediaType($mediaType);\n\n        // extract exif for the appropriate formats\n        if ($mediaType->format() === Format::JPEG) {\n            $image->setExif($this->extractExifData($path));\n        }\n","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Decoders/FilePathImageDecoder.php#L41-L77","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Convert or re-export the file to a mainstream raster format (PNG/JPEG/WebP) and retry","For TIFF/HEIC/ICO/JP2 content use the Imagick driver, which both maps and decodes those formats","Validate uploads by sniffed MIME (finfo) against a whitelist before saving/reading, not just by extension"],"exampleFix":"// before\n$image = $manager->read($storedPath); // file is actually SVG named badge.png\n// ImageDecoderException: File contains unsupported image format\n\n// after\n$mime = mime_content_type($storedPath);\nif (!in_array($mime, ['image/jpeg','image/png','image/gif','image/webp','image/avif','image/bmp'], true)) {\n    unlink($storedPath);\n    throw new RuntimeException('Rejected non-image or unsupported file, detected as ' . $mime);\n}\n$image = $manager->read($storedPath);","handlingStrategy":"try-catch","validationCode":"$mime = mime_content_type($path);\n$gdReadable = ['image/jpeg','image/png','image/gif','image/webp','image/avif','image/bmp'];\nif (!in_array($mime, $gdReadable, true)) {\n    throw new RuntimeException('File not readable as a GD-supported image, detected: ' . $mime);\n}","typeGuard":null,"tryCatchPattern":"try {\n    $image = $manager->read($path);\n} catch (\\Intervention\\Image\\Exceptions\\ImageDecoderException $e) {\n    // generic wrapper: re-diagnose with mime_content_type() to find the real cause\n    $mime = mime_content_type($path);\n}","preventionTips":["Validate uploads by finfo-sniffed MIME, never by extension alone","Scan media directories separately from processing so one bad file cannot stall batches","Log the detected MIME alongside the failure to unmask the swallowed cause"],"tags":["file-path","unsupported-format","mime-type","decoder","gd-driver","file-upload"],"backgroundTag":"unsupported-image-format","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}