What causes "Invalid image: %s" in PHPOffice/PHPWord?

Verify the path with is_file and that getimagesize() returns an array before calling setImageValue

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

Invalid image

Error message

Invalid image: %s

What it means

TemplateProcessor::prepareImageAttrs verifies an image file by calling getimagesize on the resolved path; if it does not return an array (file missing, unreadable, or not a real image), it throws 'Invalid image: %s' with the path. This guards the placeholder-replacement image feature against unusable image files.

Solutions

Verify the path with is_file and that getimagesize() returns an array before calling setImageValue
Use an absolute path or resolve relative to __DIR__
Re-generate or re-save the image if the file is corrupt (open it with an image editor to confirm)
Check read permissions on the image file

Example fix

// before
$template->setImageValue('${logo}', ['path' => 'logo.png']);
// after
$path = __DIR__ . '/logo.png';
if (!is_file($path) || getimagesize($path) === false) {
    throw new RuntimeException('Image missing or invalid: ' . $path);
}
$template->setImageValue('${logo}', ['path' => $path]);

Defensive patterns

Strategy: validation

Validate before calling

$path = __DIR__ . '/logo.png';
if (!is_file($path) || !is_readable($path) || getimagesize($path) === false) {
    throw new RuntimeException("Image invalid or unreadable: $path");
}
$template->setImageValue('${logo}', ['path' => $path]);

Type guard

function isUsableImage(?string $path): bool {
    return $path !== null && is_file($path) && is_readable($path) && is_array(@getimagesize($path));
}

Try / catch

try {
    $template->setImageValue('${logo}', ['path' => $imgPath]);
} catch (\PhpOffice\PhpWord\Exception\Exception $e) {
    if (str_starts_with($e->getMessage(), 'Invalid image:')) {
        // log path, substitute a placeholder image or skip
    }
}

Prevention

Resolve image paths absolutely (relative paths depend on CWD)
Confirm uploads are real images with getimagesize before storing
Check file existence right before template processing
Handle async upload/generation failures instead of failing silently

When it happens

Trigger: setImageValue('${placeholder}', ['path' => '/missing.png']) when the file does not exist, the path is wrong, the file is corrupted or not a real image (e.g. renamed text file), or PHP lacks permission to read it.

Common situations: Relative paths resolved against a wrong working directory (CLI vs web server); files deleted between upload and template processing; images generated by an earlier step that failed silently; unsupported/legacy formats like some TIFF/WebP depending on the PHP build.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at src/PhpWord/TemplateProcessor.php:568

            if (isset($replaceImage['width'])) {
                $width = $replaceImage['width'];
            }
            if (isset($replaceImage['height'])) {
                $height = $replaceImage['height'];
            }
            if (isset($replaceImage['ratio'])) {
                $ratio = $replaceImage['ratio'];
            }
        } else {
            $imgPath = $replaceImage;
        }

        $width = $this->chooseImageDimension($width, $varInlineArgs['width'] ?? null, 115);
        $height = $this->chooseImageDimension($height, $varInlineArgs['height'] ?? null, 70);

        $imageData = @getimagesize($imgPath);
        if (!is_array($imageData)) {
            throw new Exception(sprintf('Invalid image: %s', $imgPath));
        }
        [$actualWidth, $actualHeight, $imageType] = $imageData;

        // fix aspect ratio (by default)
        if (null === $ratio && isset($varInlineArgs['ratio'])) {
            $ratio = $varInlineArgs['ratio'];
        }
        if (null === $ratio || !in_array(strtolower($ratio), ['', '-', 'f', 'false'])) {
            $this->fixImageWidthHeightRatio($width, $height, $actualWidth, $actualHeight);
        }

        $imageAttrs = [
            'src' => $imgPath,
            'mime' => image_type_to_mime_type($imageType),
            'width' => $width,
            'height' => $height,
        ];

View on GitHub (pinned to aef95c0415)