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

PDF rendering library or library path has not been defined.

Error message

PDF rendering library or library path has not been defined.

What it means

The PDF writer delegates rendering to an external library (Dompdf/TCPDF/MPDF) configured via Settings::setPdfRendererName() and Settings::setPdfRendererPath(). The constructor requires both to be configured; if either is null the PDF backend is unusable and it throws before any rendering is attempted.

Solutions

Configure both settings before constructing the writer: Settings::setPdfRendererName(Settings::PDF_RENDERER_DOMPDF) and Settings::setPdfRendererPath('/path/to/dompdf').
Ensure the chosen rendering library is installed (composer require dompdf/dompdf) and its path is correct.
Verify with Settings::getPdfRendererName()/getPdfRendererPath() before creating the writer.
Wrap writer construction in try/catch and fall back to another export format (e.g. HTML) when PDF support is not configured.

Example fix

// before
$writer = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'PDF'); // throws: renderer not defined
// after
Settings::setPdfRendererName(Settings::PDF_RENDERER_DOMPDF);
Settings::setPdfRendererPath('/var/www/vendor/dompdf/dompdf');
$writer = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'PDF');
$writer->save('doc.pdf');

Defensive patterns

Strategy: validation

Validate before calling

function pdfConfigured(): bool {
    return \PhpOffice\PhpWord\Settings::getPdfRendererName() !== null
        && \PhpOffice\PhpWord\Settings::getPdfRendererPath() !== null;
}
// call before: if (!pdfConfigured()) { configurePdfRenderer(); }

Try / catch

try {
    $writer = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'PDF');
} catch (\PhpOffice\PhpWord\Exception\Exception $e) {
    if (str_contains($e->getMessage(), 'PDF rendering library')) {
        Settings::setPdfRendererName(Settings::PDF_RENDERER_DOMPDF);
        Settings::setPdfRendererPath($dompdfPath);
        $writer = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'PDF');
    } else { throw $e; }
}

Prevention

Centralize PDF renderer settings in bootstrap config loaded in every entry point (web + CLI + workers).
Verify the renderer library is installed and its path exists at deploy time.
Add a health check that asserts getPdfRendererName()/Path() are non-null.
Document the required Settings calls where the PDF writer is first used in the codebase.

When it happens

Trigger: Creating a PDF writer (e.g. IOFactory::createWriter($phpWord, 'PDF')) without first calling Settings::setPdfRendererName() and Settings::setPdfRendererPath(); config set in one environment but missing in another; library path pointing outside available include paths.

Common situations: New deployments where the PDF bootstrap code was omitted; using the 'PDF' writer for the first time; framework config files not loaded in CLI workers; upgrading PhpWord where default renderer settings changed.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at src/PhpWord/Writer/PDF.php:48

 */
class PDF
{
    /**
     * The wrapper for the requested PDF rendering engine.
     *
     * @var AbstractRenderer
     */
    private $renderer;

    /**
     * Instantiate a new renderer of the configured type within this container class.
     */
    public function __construct(PhpWord $phpWord)
    {
        $pdfLibraryName = Settings::getPdfRendererName();
        $pdfLibraryPath = Settings::getPdfRendererPath();
        if (null === $pdfLibraryName || null === $pdfLibraryPath) {
            throw new Exception('PDF rendering library or library path has not been defined.');
        }

        $includePath = str_replace('\\', '/', get_include_path());
        $rendererPath = str_replace('\\', '/', $pdfLibraryPath);
        if (strpos($rendererPath, $includePath) === false) {
            set_include_path(get_include_path() . PATH_SEPARATOR . $pdfLibraryPath);
        }

        $rendererName = static::class . '\\' . $pdfLibraryName;
        $this->renderer = new $rendererName($phpWord);
    }

    /**
     * Magic method to handle direct calls to the configured PDF renderer wrapper class.
     *
     * @param string $name Renderer library method name
     * @param mixed[] $arguments Array of arguments to pass to the renderer method
     *

View on GitHub (pinned to aef95c0415)