PHPOffice/PHPWord · error · PhpOffice\PhpWord\Exception\Exception

Unsupported image type $imageMimeType

Error message

Unsupported image type $imageMimeType

What it means

TemplateProcessor::addImageToRelations maps the detected image MIME type to a file extension via an $extTransform whitelist; if the MIME type is not in the map it throws "Unsupported image type $imageMimeType". Only image types that can be embedded in OOXML media with a known extension are supported.

Solutions

1. Convert the image to JPEG or PNG before embedding (e.g. with GD or Imagick)
2. Use only jpg/png/gif sources for template images
3. Normalize the image's MIME type on upload/processing pipelines so it matches the whitelist

Example fix

// before
$template->setImageValue('${photo}', ['path' => 'photo.webp']); // throws
// after
$im = imagecreatefromwebp('photo.webp');
imagejpeg($im, 'photo.jpg', 90);
$template->setImageValue('${photo}', ['path' => 'photo.jpg']);

$mime = (new finfo(FILEINFO_MIME_TYPE))->file($imgPath);
$allowed = ['image/jpeg','image/png','image/gif'];
if (!in_array($mime, $allowed, true)) {
    $imgPath = convertToJpeg($imgPath); // GD/Imagick conversion
}

function isEmbeddableImageType(string $mime): bool {
    return in_array($mime, ['image/jpeg','image/png','image/gif'], true);
}

try {
    $template->setImageValue('${photo}', ['path' => $imgPath]);
} catch (\PhpOffice\PhpWord\Exception\Exception $e) {
    if (str_contains($e->getMessage(), 'Unsupported image type')) {
        // convert to JPEG/PNG and retry
    }
}

When it happens

Trigger: setImageValue with an image whose MIME type is not one of the supported set (e.g. image/webp, image/svg+xml, image/bmp, image/tiff depending on the transform map).

Common situations: Uploading modern WebP or SVG images and injecting them into a .docx template; images served/saved with unusual MIME types; camera images in TIFF format.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Invalid image
• Invalid image
• Could not load image $originSrc
• Could not load the given XML document.
• Could not transform the given XML document.

AI-assisted analysis of PHPOffice/PHPWord@aef95c0415 (2026-09-14). Data as JSON: /api/errors/be82eee4a45a55ee. Report an issue: GitHub.

Appendix: source

Thrown at src/PhpWord/TemplateProcessor.php:612

        $relationTpl = '<Relationship Id="{RID}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/{IMG}"/>';
        $newRelationsTpl = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' . "\n" . '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"></Relationships>';
        $newRelationsTypeTpl = '<Override PartName="/{RELS}" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>';
        $extTransform = [
            'image/jpeg' => 'jpeg',
            'image/png' => 'png',
            'image/bmp' => 'bmp',
            'image/gif' => 'gif',
        ];

        // get image embed name
        if (isset($this->tempDocumentNewImages[$imgPath])) {
            $imgName = $this->tempDocumentNewImages[$imgPath];
        } else {
            // transform extension
            if (isset($extTransform[$imageMimeType])) {
                $imgExt = $extTransform[$imageMimeType];
            } else {
                throw new Exception("Unsupported image type $imageMimeType");
            }

            // add image to document
            $imgName = 'image_' . $rid . '_' . pathinfo($partFileName, PATHINFO_FILENAME) . '.' . $imgExt;
            $this->zipClass->pclzipAddFile($imgPath, 'word/media/' . $imgName);
            $this->tempDocumentNewImages[$imgPath] = $imgName;

            // setup type for image
            $xmlImageType = str_replace(['{IMG}', '{EXT}'], [$imgName, $imgExt], $typeTpl);
            $this->tempDocumentContentTypes = str_replace('</Types>', $xmlImageType, $this->tempDocumentContentTypes) . '</Types>';
        }

        $xmlImageRelation = str_replace(['{RID}', '{IMG}'], [$rid, $imgName], $relationTpl);

        if (!isset($this->tempDocumentRelations[$partFileName])) {
            // create new relations file
            $this->tempDocumentRelations[$partFileName] = $newRelationsTpl;
            // and add it to content types

View on GitHub (pinned to aef95c0415)