PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Unsupported image type in comment background. Supported type

Error message

Unsupported image type in comment background. Supported types: PNG, JPEG, BMP, GIF.

What it means

When the Xlsx writer stores a Drawing's image in xl/media it builds the entry name in getMediaFilename(), which requires the image's GD type constant to be a key of Drawing::IMAGE_TYPES_CONVERTION_MAP — only GIF, JPEG, PNG and BMP are listed (GIF/BMP are converted to PNG). The type is detected from the file's real bytes via getimagesize() in setSizesAndType(); the default is IMAGETYPE_UNKNOWN, which also fails the check. The 'comment background' wording is historical — the guard applies to every drawing you attach.

Source

Thrown at src/PhpSpreadsheet/Worksheet/Drawing.php:76

     * Get Extension.
     */
    public function getExtension(): string
    {
        if (Preg::isMatch('~^data:image/([^;]+);base64,~', $this->path, $matches)) {
            return $matches[1];
        }
        $exploded = explode('.', basename($this->path));

        return $exploded[count($exploded) - 1];
    }

    /**
     * Get full filepath to store drawing in zip archive.
     */
    public function getMediaFilename(): string
    {
        if (!array_key_exists($this->type, self::IMAGE_TYPES_CONVERTION_MAP)) {
            throw new PhpSpreadsheetException('Unsupported image type in comment background. Supported types: PNG, JPEG, BMP, GIF.');
        }

        return sprintf('image%d%s', $this->getImageIndex(), $this->getImageFileExtensionForSave());
    }

    /**
     * Get Path.
     */
    public function getPath(): string
    {
        return $this->path;
    }

    /**
     * Set Path.
     *
     * @param string $path File path
     * @param bool $verifyFile Verify file

View on GitHub (pinned to 65b080eef4)

Solutions

1. Convert the image to a supported format before attaching it: $img = imagecreatefromwebp($path); imagepng($img, $tmp); $drawing->setPath($tmp);
2. Or render to a MemoryDrawing::fromString(...) after converting, so the writer always receives PNG/JPEG/GIF/BMP bytes.
3. Reject or transcode uploads at ingestion when getimagesize()[2] is not IMAGETYPE_PNG/JPEG/GIF/BMP.

Example fix

// before
$drawing = new Drawing();
$drawing->setPath('/uploads/logo.webp'); // ok at set time, writer throws later

// after
$src = imagecreatefromwebp('/uploads/logo.webp');
imagepng($src, '/tmp/logo.png');
$drawing->setPath('/tmp/logo.png');

$info = @getimagesize($imagePath);
if ($info === false || !in_array($info[2], [IMAGETYPE_PNG, IMAGETYPE_JPEG, IMAGETYPE_GIF, IMAGETYPE_BMP], true)) {
    $src = imagecreatefromstring(file_get_contents($imagePath));
    imagepng($src, $imagePath .= '.png'); // transcode to PNG
}
$drawing->setPath($imagePath);

function isSupportedDrawingImage(string $path): bool
{
    $info = @getimagesize($path);
    return $info !== false
        && in_array($info[2], [IMAGETYPE_PNG, IMAGETYPE_JPEG, IMAGETYPE_GIF, IMAGETYPE_BMP], true);
}

try {
    $writer->save($file);
} catch (PhpSpreadsheetException $e) {
    if (str_contains($e->getMessage(), 'Unsupported image type')) {
        // find the offending drawing, transcode it to PNG, then re-save
    }
}

When it happens

Trigger: $drawing->setPath('logo.webp') followed by $writer->save('out.xlsx'); TIFF, AVIF, SVG or ICO images; a file renamed to .png whose content is WEBP; EMF/WMF clip-art that passes the mime check but whose type GD cannot detect.

Common situations: Images from modern tooling (WEBP is many converters' default), CDN-served WEBP variants, SVG logos for headers, uploads accepted by extension whitelist; the exception surfaces inside save(), far away from the setPath() call.

Related errors

• Unsupported binary comparison operator
• Cloning the calculation engine is not allowed!
• Unsupported numeric binary operation
• Locale file not found
• #VALUE!

AI-assisted analysis of PHPOffice/PhpSpreadsheet@65b080eef4 (2026-08-17). Data as JSON: /api/errors/92bc62d62a9b5832. Report an issue: GitHub.