Intervention/image · error · ImageDecoderException

Failed to decode data from file "${path}" as image format "$

Error message

Failed to decode data from file "${path}" as image format "${mediaType}"

What it means

Format-specific decode failure in FilePathImageDecoder::decodeDefault: the file's MIME mapped to JPEG/WebP/PNG/AVIF/BMP, the matching imagecreatefrom{jpeg,webp,png,avif,bmp} was invoked, and it returned false. The error output from the GD call is suppressed with @, so this ImageDecoderException (including path and format) is the only signal: the file matches the format by signature but its data is corrupt/truncated, or this PHP-GD build cannot actually decode that codec.

Source

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

     *
     * @throws InvalidArgumentException
     * @throws ImageDecoderException
     * @throws StateException
     * @throws DriverException
     */
    private function decodeDefault(string $path, MediaType $mediaType): ImageInterface
    {
        $gdImage = match ($mediaType->format()) {
            Format::JPEG => @imagecreatefromjpeg($path),
            Format::WEBP => @imagecreatefromwebp($path),
            Format::PNG => @imagecreatefrompng($path),
            Format::AVIF => @imagecreatefromavif($path),
            Format::BMP => @imagecreatefrombmp($path),
            default => throw new ImageDecoderException('File contains unsupported image format'),
        };

        if ($gdImage === false) {
            throw new ImageDecoderException(
                'Failed to decode data from file "' . $path . '" as image format "' . $mediaType->value . '"',
            );
        }

        try {
            return parent::decode($gdImage);
        } catch (DecoderException) {
            throw new ImageDecoderException(
                'Failed to decode data from file "' . $path . '" as image format "' . $mediaType->value . '"',
            );
        }
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Check the runtime codec support: inspect gd_info() for WebP/AVIF support and compare with the failing format; rebuild/switch the PHP image or install the extension variant that includes it
2. Verify file integrity independently: identify it with file/mime_content_type and try opening in another tool or with the Imagick driver
3. Re-transfer or restore the file from source if corrupted (compare sizes/checksums); write uploads atomically (tmp + rename) so partial files are not read
4. Catch ImageDecoderException and trigger a re-fetch/re-export path instead of retrying the same bytes

Example fix

// before
$image = $manager->read('/storage/a/photo.webp');
// ImageDecoderException: Failed to decode data from file "..." as image format "image/webp"

// after
if (!(gd_info()['WebP Support'] ?? false)) {
    $manager = new \Intervention\Image\ImageManager(
        new \Intervention\Image\Drivers\Imagick\Driver()
    );
}
$image = $manager->read('/storage/a/photo.webp');

$formatMap = [
    'image/jpeg' => static fn($p) => @imagecreatefromjpeg($p),
    'image/webp' => static fn($p) => @imagecreatefromwebp($p),
    'image/png' => static fn($p) => @imagecreatefrompng($p),
    'image/avif' => static fn($p) => @imagecreatefromavif($p),
    'image/bmp' => static fn($p) => @imagecreatefrombmp($p),
];
$mime = mime_content_type($path);
if (!isset($formatMap[$mime]) || $formatMap[$mime]($path) === false) {
    throw new RuntimeException('GD cannot load this file (corrupt or codec missing): ' . $path);
}

try {
    $image = $manager->read($path);
} catch (\Intervention\Image\Exceptions\ImageDecoderException $e) {
    if (str_contains($e->getMessage(), 'Failed to decode data from file')) {
        // codec missing or file corrupt: check gd_info() / re-fetch source
    }
}

When it happens

Trigger: ImageManager::read('/tmp/x.webp') on a PHP-GD compiled without WebP support (function exists but decoding fails); progressive/truncated JPEG where finfo saw image/jpeg but imagecreatefromjpeg bails; AVIF files on GD < 7.4/8.x without libavif; files damaged in transfer (binary mode off); mismatched content where finfo misidentified the container.

Common situations: Debian/Ubuntu default php-gd historically lacking WebP; Alpine images missing libavif; CDN-cached corrupted variants; disk-full events leaving partial writes; matching works on dev (custom-compiled GD) but fails on prod (distro GD).

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

• Failed to read media (MIME) type from binary data
• Base64-encoded data contains unsupported image type
• Failed to decode unsupported image format from binary data
• File contains unsupported image format
• Failed to read media (MIME) type from data in file path

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