{"record":{"id":"99f8a3913d9aed74","repo":"Intervention/image","slug":"failed-to-decode-data-from-file-path-as-image","errorCode":null,"errorMessage":"Failed to decode data from file \"${path}\" as image format \"${mediaType}\"","messagePattern":"Failed to decode data from file \"(.+?)\" as image format \"(.+?)\"","errorType":"exception","errorClass":"ImageDecoderException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Decoders/FilePathImageDecoder.php","lineNumber":106,"sourceCode":"     *\n     * @throws InvalidArgumentException\n     * @throws ImageDecoderException\n     * @throws StateException\n     * @throws DriverException\n     */\n    private function decodeDefault(string $path, MediaType $mediaType): ImageInterface\n    {\n        $gdImage = match ($mediaType->format()) {\n            Format::JPEG => @imagecreatefromjpeg($path),\n            Format::WEBP => @imagecreatefromwebp($path),\n            Format::PNG => @imagecreatefrompng($path),\n            Format::AVIF => @imagecreatefromavif($path),\n            Format::BMP => @imagecreatefrombmp($path),\n            default => throw new ImageDecoderException('File contains unsupported image format'),\n        };\n\n        if ($gdImage === false) {\n            throw new ImageDecoderException(\n                'Failed to decode data from file \"' . $path . '\" as image format \"' . $mediaType->value . '\"',\n            );\n        }\n\n        try {\n            return parent::decode($gdImage);\n        } catch (DecoderException) {\n            throw new ImageDecoderException(\n                'Failed to decode data from file \"' . $path . '\" as image format \"' . $mediaType->value . '\"',\n            );\n        }\n    }\n}\n","sourceCodeStart":88,"sourceCodeEnd":120,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Decoders/FilePathImageDecoder.php#L88-L120","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["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","Verify file integrity independently: identify it with file/mime_content_type and try opening in another tool or with the Imagick driver","Re-transfer or restore the file from source if corrupted (compare sizes/checksums); write uploads atomically (tmp + rename) so partial files are not read","Catch ImageDecoderException and trigger a re-fetch/re-export path instead of retrying the same bytes"],"exampleFix":"// before\n$image = $manager->read('/storage/a/photo.webp');\n// ImageDecoderException: Failed to decode data from file \"...\" as image format \"image/webp\"\n\n// after\nif (!(gd_info()['WebP Support'] ?? false)) {\n    $manager = new \\Intervention\\Image\\ImageManager(\n        new \\Intervention\\Image\\Drivers\\Imagick\\Driver()\n    );\n}\n$image = $manager->read('/storage/a/photo.webp');","handlingStrategy":"try-catch","validationCode":"$formatMap = [\n    'image/jpeg' => static fn($p) => @imagecreatefromjpeg($p),\n    'image/webp' => static fn($p) => @imagecreatefromwebp($p),\n    'image/png' => static fn($p) => @imagecreatefrompng($p),\n    'image/avif' => static fn($p) => @imagecreatefromavif($p),\n    'image/bmp' => static fn($p) => @imagecreatefrombmp($p),\n];\n$mime = mime_content_type($path);\nif (!isset($formatMap[$mime]) || $formatMap[$mime]($path) === false) {\n    throw new RuntimeException('GD cannot load this file (corrupt or codec missing): ' . $path);\n}","typeGuard":null,"tryCatchPattern":"try {\n    $image = $manager->read($path);\n} catch (\\Intervention\\Image\\Exceptions\\ImageDecoderException $e) {\n    if (str_contains($e->getMessage(), 'Failed to decode data from file')) {\n        // codec missing or file corrupt: check gd_info() / re-fetch source\n    }\n}","preventionTips":["Verify gd_info() flags for WebP/AVIF in every deployment environment","Write uploads atomically (temp file + rename) so partial files are never read","Cross-check file sizes with the client/upstream before decoding"],"tags":["gd-driver","corrupt-file","webp","avif","codec-support","file-path","decoder"],"backgroundTag":"corrupt-image-file","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}