Start by checking the exact src value in the HTML passed to Dompdf, then classify it as a local filesystem path, an http(s) URL, or a data: URI. Local files must be readable by the PHP process and inside Dompdf’s configured chroot; remote images require isRemoteEnabled and working PHP network support. Only after those checks should you investigate image format, extensions, or SVG behavior.
Identify what kind of image source Dompdf receives
A browser-facing URL, a server filesystem path, and a data URI are different kinds of image sources. They have different access rules, so applying a remote-image setting to a local path—or changing a filesystem path when the HTML contains a URL—will not fix the underlying problem.
Source in src |
What it means | First checks |
|---|---|---|
| Filesystem path | A path on the machine running PHP, such as /srv/app/public/images/logo.png |
Resolve it to an absolute path; test PHP read access; check the resolved path against chroot. |
http:// or https:// |
A resource Dompdf must fetch over the network | Check isRemoteEnabled, cURL or allow_url_fopen, reachability, redirects, and access requirements. |
data: |
Image content embedded in the HTML | Check the MIME type, encoding, payload, and—especially for SVG—the installed Dompdf version and security implications. |
Do not infer the source from what works in a browser. A URL such as /images/logo.png is usually an application route, not a filesystem path Dompdf can read. Conversely, a server path such as /srv/app/public/images/logo.png is not a URL a browser can fetch.
Inspect the HTML and resolve the source first
Inspect the final HTML immediately before the render call, not just the template or the page you see in a browser. Log or print the image’s actual src. Look for an empty value, incorrectly escaped characters, a relative path, a stale or expired signed URL, or a path assembled using an unexpected working directory.
#1 Best Overall
For a local asset, build an absolute filesystem path from a stable location in your application. For example, if the PHP file and an images directory are in the same project tree:
$imagePath = realpath(__DIR__ . '/images/logo.png');
if ($imagePath === false || !is_readable($imagePath)) {
throw new RuntimeException('Logo is missing or unreadable: ' . __DIR__ . '/images/logo.png');
}
$html = '<img src="' . htmlspecialchars($imagePath, ENT_QUOTES, 'UTF-8') . '" alt="Logo">';The example verifies that PHP can resolve and read the file; Dompdf must still be allowed to access its location. Check the real target of symlinks as well as the path spelling: a path that appears to be under an allowed directory may resolve outside it.
For remote images, inspect the exact URL generated for the PDF job. If it depends on browser cookies, an authorization header, a session, or a signed link that has expired, the rendering process may not receive the same content as your browser. Check the URL from the same server and runtime that generates the PDF.
Fix local filesystem paths and chroot access
Dompdf restricts local file access to configured chroot path(s). A local image outside those permitted paths can fail even when the file exists and the PHP user can read it. The project’s README and usage guidance describe the chroot restriction; Dompdf.net’s image-loading guide recommends absolute paths and checking read permissions.
- Resolve the full path. Use
realpath()and confirm the result is notfalse. Check the path in the production environment, where deployment directories may differ from development. - Check PHP readability. Use
is_readable()in the process that renders the PDF, and confirm the file’s directory permissions permit traversal. - Compare against chroot. Configure Dompdf’s allowed root to include the image directory, or move bundled assets into an already permitted application directory. Keep the scope as narrow as the application permits.
- Check symlinks and deployment layout. Compare the resolved target with the allowed root, and verify that the asset exists in the container, release, or worker that actually creates the PDF.
For logos, signatures, and invoice graphics that must render predictably, a bundled local asset under an explicitly permitted directory avoids dependence on an external network. It still depends on the correct production path, permissions, and chroot configuration.
Fix remote HTTP and HTTPS images
Remote resource loading is disabled by default in Dompdf’s project guidance. To fetch an external image, enable isRemoteEnabled in the options used by the render job. The PHP runtime also needs either cURL or allow_url_fopen enabled, as described in the Dompdf README.
Rank #3
use DompdfDompdf;
use DompdfOptions;
$options = new Options();
$options->set('isRemoteEnabled', true);
$dompdf = new Dompdf($options);
$dompdf->loadHtml($html);
$dompdf->render();
$dompdf->stream('document.pdf');Use this setting only when remote resources are needed. Fetching a URL from a document can make the server issue requests to destinations chosen through that document. If users can submit HTML or URLs, do not let arbitrary input reach an unrestricted remote renderer: accept trusted sources and restrict permitted hosts in your application.
Check the PHP configuration in the actual runtime that executes the job. PHP-FPM, a web-server module, a queue worker, and CLI PHP can use different configuration files and extensions. A setting that works in a local CLI test does not establish that the production worker has it.
- Confirm the resolved URL returns the intended image from the PDF server.
- Check redirects, TLS certificate validation, DNS resolution, outbound firewall rules, and proxy requirements.
- Check whether the target requires cookies, browser-only authorization, or headers the renderer is not sending.
- Prefer local assets for important graphics when external availability is not essential.
Check extensions, image formats, and SVG behavior
The Dompdf README lists GD for image processing and discusses GIF, PNG, BMP, and JPEG support. It also names DOM, MBString, php-font-lib, and php-svg-lib in its requirements and dependency discussion. Dependency requirements can change between releases, so compare the installed version’s requirements with the extensions installed in the PDF job’s runtime rather than relying on an old PHP-version checklist.
If a PNG with transparency fails while another simple image works, check GD and the installed release’s requirements. Dompdf.net’s troubleshooting guidance also identifies GD as relevant to PNG alpha processing. Use a known-good supported raster image as a controlled diagnostic, then reintroduce the original format once path and access are established.
Raw inline SVG markup—an <svg>…</svg> element directly in the HTML—is described as unsupported in the Dompdf README. Its suggested alternatives are an external SVG file or an SVG data URI. These are not universal fixes: external files remain subject to path, chroot, or remote-resource rules, and data-URI SVG handling depends on the installed version and security policy.
A Dompdf project security advisory published July 20, 2026, identifies versions through 3.1.5 as affected by a local-file-read issue involving SVG images encoded as data URIs and lists 3.1.6 as patched. Check the installed version and upgrade to a patched release if affected, particularly before processing untrusted documents. Do not treat an SVG data URI as a safe workaround for untrusted input.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsChoose the right source strategy
| Approach | Good fit | Main checks | Trade-off |
|---|---|---|---|
| Local filesystem asset | Bundled logos and images that should be available offline | Absolute path, PHP read permission, real target under chroot |
Production paths and deployment contents must match the configuration. |
| Remote HTTP(S) | Content that must be fetched from an external service | isRemoteEnabled, cURL or allow_url_fopen, network access, URL access rules |
Depends on network and remote availability; can create server-side request risk if inputs are untrusted. |
| Data URI | Self-contained image content or avoiding filesystem path resolution | Correct MIME type and encoding; installed-version behavior | Can enlarge the HTML; SVG data URIs require particular security and version care. |
| External SVG | Vector artwork that cannot be represented as raster | Version-specific SVG support plus normal path or remote-resource permissions | Still subject to resource rules and security concerns. |
Use a controlled triage sequence
Change one variable at a time so a working fix identifies the cause rather than masking it.
- Render a minimal document with one known-good local raster image inside the configured chroot.
- If it is missing, inspect the resolved path, PHP read permissions, and the process’s actual chroot configuration.
- If the failing source is remote, check
isRemoteEnabled, cURL orallow_url_fopen, server reachability, redirects, TLS, and required authentication. - Try a known-good supported raster format. If image processing appears implicated, verify GD in the same runtime.
- Check SVG-specific markup and the installed Dompdf version, especially when a data URI or untrusted document is involved.
- Add stylesheets, dynamic content, and other assets back gradually. Recheck each asset’s final
srcrather than assuming all images share one cause.
Troubleshoot by symptom
| Symptom | Likely area to inspect | Next action |
|---|---|---|
| Local image works in a browser but not in the PDF | URL/path confusion or chroot | Use and log the absolute filesystem path; resolve symlinks and compare the real path to the allowed root. |
| Local image exists but remains blank | PHP permissions or different production path | Run realpath() and is_readable() in the rendering process; check directory traversal permissions. |
| Remote image is missing | Remote resources disabled or PHP cannot fetch | Check isRemoteEnabled, cURL or allow_url_fopen, then test network and URL access from the PDF server. |
| Remote URL works only in a browser | Cookies, headers, redirect, signed URL, or authentication difference | Verify the PDF process can retrieve the same image without relying on browser-only state. |
| One image format fails while a simple raster works | Format support, extension, or SVG handling | Verify the installed release’s dependencies and format guidance; check GD for image processing. |
| Inline SVG is blank or untrusted SVG is involved | Unsupported inline markup or version-sensitive SVG security | Use a supported approach only after checking the installed version; upgrade if affected by the advisory. |
Or skip the browser setup
If the image you need is part of a publicly accessible webpage, ScreenshotNeo can return a screenshot you can use as an image asset in a document. It is a separate capture route, not a fix for Dompdf’s filesystem permissions, chroot, or remote-resource configuration.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, and cache hits are not billed. Its MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
How can I tell whether an image source is local or remote?
Inspect the final HTML’s src: an absolute server path is local, an http(s) address is remote, and a data: value embeds the image.
Recommended Free Tools
Can I use raw inline SVG markup in Dompdf?
The project README describes raw inline SVG markup as unsupported; check the installed release’s guidance for alternatives.
What Dompdf version addresses the SVG data-URI local-file-read advisory?
The advisory published July 20, 2026, lists 3.1.6 as patched for the issue affecting versions through 3.1.5.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
