dompdf : image not found or type unknown

dompdf : image not found or type unknown

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

dompdf: Image Not Found or Type Unknown

When generating PDFs with dompdf, encountering a "image not found" or "type unknown" error usually points to one of two things: the server cannot reach the file path you provided, or the image format isn't supported by the rendering engine. In the specific scenario where DOMPDF_ENABLE_REMOTE is set to true, many developers assume the library will automatically fetch external URLs. However, this setting only affects how DOMPDF handles remote resources relative to the document's base URL; it does not grant permission to access arbitrary local filesystem paths like /var/htdocs/PDF/header.png.

The root cause in the provided code snippet is the use of an absolute filesystem path (/var/htdocs/PDF/header.png) within a PHP string that DOMPDF treats as HTML. DOMPDF operates strictly within the context of the web server's document root or specific asset directories defined in its configuration. When you pass a raw path starting with /, DOMPDF attempts to resolve it relative to the base URL configured in dompdf_config.inc.php, not the raw filesystem root of the OS. Unless your base_path is explicitly set to match that exact directory structure, the lookup fails before the image is even loaded.

To resolve this, you must ensure the path provided to the <img> tag is relative to the document's base URL or points to a location where DOMPDF has read access and permission to serve the file. If your images reside in /var/htdocs/PDF/, you need to configure DOMPDF to recognize this directory as an asset source. This typically involves modifying the dompdf_config.inc.php file, specifically adjusting the base_path or ensuring the image path is relative to the web root (e.g., /PDF/header.png) rather than an absolute OS path.

Another critical consideration is the security model of your PHP environment. Even if the path is correct, the underlying web server configuration (Apache/Nginx) and PHP's open_basedir restrictions might prevent DOMPDF from reading files outside the allowed directory. If you are running this code within a Laravel application or similar framework, ensure that the public folder structure is respected and that the image URL matches the public URL path accessible via HTTP, not the internal filesystem path.

If you require more control over resource loading, particularly for base64-encoded images or complex asset management, consider leveraging specific DOMPDF configurations to whitelist directories. For instance, setting up a custom asset_base_url can help normalize how paths are interpreted. Additionally, checking the log_output_file_path in your configuration is often the first step in debugging these issues; reviewing the generated log file will reveal whether the error stems from a missing file, an unsupported format (like WEBP without proper support), or a permissions issue.

While DOMPDF_ENABLE_REMOTE allows loading images from HTTP/HTTPS URLs, it does not bypass filesystem security constraints for local paths. If you must use local files, ensure the path is relative to the document root and that the file permissions allow the web server user (often www-data or nginx) to read the image.

For developers looking to streamline PDF generation within the Laravel ecosystem, resources like https://laravelcompany.com offer community-driven insights on handling asset management in production environments, which can be particularly useful when integrating complex rendering libraries. However, the fundamental fix remains ensuring that the path provided to DOMPDF aligns with its configured base URL and adheres to server-side security boundaries.

Our network