PHPOffice/PHPWord · error · RuntimeException

The GD extension is required to process GD images.

Error message

The GD extension is required to process GD images.

What it means

When an Image was created from a GD image resource (SOURCE_GD), getImageString() must re-encode the image via the PHP GD extension. If ext-gd is not loaded, a RuntimeException is thrown because the image cannot be serialized into the document. This is an environment/extension problem, not a data problem.

Solutions

1. Install/enable the GD extension: e.g. apt-get install php-gd or docker-php-ext-install gd, then restart PHP.
2. Verify with extension_loaded('gd') or php -m | grep gd before processing GD images.
3. Load the image from a file path or binary string instead of a GD resource, avoiding the GD code path.
4. Add ext-gd to composer.json require so deployment tooling enforces it.

Example fix

// before
$image = new Image($section, $gdResource);
// after
if (!extension_loaded('gd')) { throw new RuntimeException('Enable ext-gd'); }
$image = new Image($section, $gdResource);

if (!extension_loaded('gd')) {
    // avoid the GD source path; load image from file/bytes instead
}

function gdAvailable(): bool { return extension_loaded('gd') && function_exists('imagecreatefromstring'); }

try { $data = $image->getImageStringData(); } catch (\RuntimeException $e) { $data = file_get_contents($imagePath); }

When it happens

Trigger: Creating an Image from a GD resource (e.g. imagecreatefrompng) and calling getImageString()/getImageStringData() on a PHP build compiled without GD.

Common situations: Minimal Docker/Alpine PHP images without php-gd, shared hosting without GD enabled, or forgetting to install/enable the extension after a PHP upgrade.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

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/e9bb3f5893aa7e0f. Report an issue: GitHub.

Appendix: source

Thrown at src/PhpWord/Element/Image.php:403

                    $actualSource = Settings::getTempDir() . DIRECTORY_SEPARATOR . $imageFilename;
                }
            }
            $zip->close();
        } else {
            $actualSource = $source;
        }

        // Can't find any case where $actualSource = null hasn't captured by
        // preceding exceptions. Please uncomment when you find the case and
        // put the case into Element\ImageTest.
        // if ($actualSource === null) {
        //     return null;
        // }

        // Read image binary data and convert to hex/base64 string
        if ($this->sourceType == self::SOURCE_GD) {
            if (!extension_loaded('gd')) {
                throw new RuntimeException('The GD extension is required to process GD images.');
            }
            $imageResource = call_user_func($this->imageCreateFunc, $actualSource);
            if ($this->imageType === 'image/png') {
                // PNG images need to preserve alpha channel information
                imagesavealpha($imageResource, true);
            }
            ob_start();
            $callback = $this->imageFunc;
            $callback($imageResource);
            $imageBinary = ob_get_contents();
            ob_end_clean();
        } elseif ($this->sourceType == self::SOURCE_STRING) {
            $imageBinary = $this->source;
        } else {
            $fileHandle = fopen($actualSource, 'rb', false);
            $fileSize = filesize($actualSource);
            if ($fileHandle !== false && $fileSize > 0) {
                $imageBinary = fread($fileHandle, $fileSize);

View on GitHub (pinned to aef95c0415)