PHPOffice/PHPWord · error · Exception

Image object not assigned.

Error message

Image object not assigned.

What it means

Media::addElement throws this when asked to register a media element of type 'image' but no Image instance was supplied. The library requires an actual Image object to derive extension, type, and content; without it the media relationship cannot be created.

Solutions

1. Construct a valid Image (e.g. via Image::fromFile or fromString) before calling Media::addElement
2. Guard the call: skip or throw a clearer error when $image is null
3. Check that any function returning the Image is not returning null on error paths

Example fix

// before
Media::addElement('image', $section, $image); // $image is null
// after
if ($image === null) {
    $image = new Image($imagePath);
}
Media::addElement('image', $section, $image);

if ($image === null) { throw new \InvalidArgumentException('An Image object is required'); }

function isImage($image): bool { return $image instanceof \PhpOffice\PhpWord\Element\Image; }

try { Media::addElement('image', $section, $image); } catch (\Exception $e) { if ($e->getMessage() === 'Image object not assigned.') { /* handle missing image */ } throw $e; }

When it happens

Trigger: Calling addElement('image', ...) with a null $image parameter — e.g. Media::addElement('image', $mediaSection, $image) where $image was never constructed or an earlier lookup returned null.

Common situations: Conditional image loading that silently leaves the variable null; a helper returning null instead of an Image on failure; refactoring that drops the Image argument from the call.

Related errors

• Invalid value, on of ' . implode(', ', $position) . '…
• Invalid value, on of ' . implode(', ', $restartNumbers) . '…
• Invalid value, dirty or clean possible
• Invalid value, alignments of ' . implode(', '…
• Cannot add in .

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

Appendix: source

Thrown at src/PhpWord/Media.php:69

        $mediaId = md5($container . $source);
        if (!isset(self::$elements[$container])) {
            self::$elements[$container] = [];
        }

        // Add media if not exists or point to existing media
        if (!isset(self::$elements[$container][$mediaId])) {
            $mediaCount = self::countElements($container);
            $mediaTypeCount = self::countElements($container, $mediaType);
            ++$mediaTypeCount;
            $rId = ++$mediaCount;
            $target = null;
            $mediaData = ['mediaIndex' => $mediaTypeCount];

            switch ($mediaType) {
                // Images
                case 'image':
                    if (null === $image) {
                        throw new Exception('Image object not assigned.');
                    }
                    $isMemImage = $image->isMemImage();
                    $extension = $image->getImageExtension();
                    $mediaData['imageExtension'] = $extension;
                    $mediaData['imageType'] = $image->getImageType();
                    if ($isMemImage) {
                        $mediaData['isMemImage'] = true;
                        $mediaData['imageString'] = $image->getImageString();
                    }
                    $target = "{$container}_image{$mediaTypeCount}.{$extension}";
                    $image->setTarget($target);
                    $image->setMediaIndex($mediaTypeCount);

                    break;
                    // Objects
                case 'object':
                    $target = "{$container}_oleObject{$mediaTypeCount}.bin";

View on GitHub (pinned to aef95c0415)