Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If images disappear from a PDF made with phpwkhtmltopdf, first check which file or URL the renderer is actually given and whether the wkhtmltopdf process can read or fetch each image. Relative paths depend on that input context, and local-file access may be restricted. Then check the installed binary, image-loading options, and resource errors. There is no single fix for every missing image: the right one depends on whether the image is local, remote, or inserted by JavaScript.
How phpwkhtmltopdf loads images
phpwkhtmltopdf is a PHP wrapper around the separate wkhtmltopdf executable. The wrapper must be able to find and run that binary; the binary, in turn, renders the supplied document and loads its resources. A page that looks correct in your desktop browser can still produce a PDF with missing images because the server-side conversion process may have a different filesystem, network access, permissions, or renderer build.
The wrapper can be given a filename, an HTML string, a URL, or an options array. That choice determines what a relative image path means. Before changing an image’s src, identify the exact input passed to the converter and resolve the path against that input’s base context.
Identify which kind of image is missing
Images referenced by a local HTML file
For an HTML file such as /srv/app/reports/report.html, a relative reference like images/chart.png ordinarily points to /srv/app/reports/images/chart.png. Confirm that this is where the file actually is, and check capitalization: Linux filesystems commonly distinguish Chart.png from chart.png. Also verify the file is readable by the account running PHP or the conversion process, not merely by your own login.
#1 Best Overall
- Create and edit PDFs. Collaborate with ease. E-sign documents and collect signatures. Get everything done in one app, wherever you go.
- Edit text and images without jumping to another app.
- E-sign documents or request e-signatures on any device. Recipients don’t need to log in to e-sign.
- Convert PDFs to editable Microsoft Word, Excel, or PowerPoint documents.
- Share PDFs for collaboration. Commenting features make it easy for reviewers to comment, mark up, and annotate.
Images referenced by an HTML string
An HTML string has no useful filesystem directory of its own unless you provide a base context. A relative URL such as images/chart.png may therefore fail or resolve somewhere other than expected. Use a valid absolute URL for a remote asset, or an appropriate absolute local path and permitted local-file access. If your HTML includes a <base> element, check that it points to the intended base; it can change how relative references resolve.
Images in a remote page
When the input is a URL, test the image URL from the same server or container and under the same account that runs conversion. A successful load on your workstation does not establish that the renderer can reach it. Check DNS, redirects, HTTP response status, authentication, proxy requirements, and TLS certificate validation in that environment.
Fix local-file access safely
The wkhtmltopdf command manual documents local-file access controls. In the documented manual, local access is disabled by default: a local input cannot freely read other local files unless access is enabled or a path is permitted. This is a common reason for local images or stylesheets to vanish.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Approach | Example | Scope and trade-off |
|---|---|---|
| Allow a specific path | --allow /srv/app/reports/assets |
Narrower access. Prefer this when the renderer only needs a known asset directory. |
| Enable local-file access | --enable-local-file-access |
Broader access to local files. Use only with trusted input and a deliberate security review. |
For example, if the HTML and assets are trusted and the image files live under /srv/app/reports/assets, try:
Rank #2
![Acrobat Pro | 1-Month Subscription | PDF Software |Convert, Edit, E-Sign, Protect |Activation Required [PC/Mac Online Code]](https://m.media-amazon.com/images/I/41CUq+X3jVL._SL160_.jpg)
- Create and edit PDFs. Collaborate with ease. E-sign documents and collect signatures. Get everything done in one app, wherever you go.
- Edit text and images without jumping to another app.
- E-sign documents or request e-signatures on any device. Recipients don’t need to log in to e-sign.
- Convert PDFs to editable Microsoft Word, Excel, or PowerPoint documents.
- Share PDFs for collaboration. Commenting features make it easy for reviewers to comment, mark up, and annotate.
wkhtmltopdf --allow /srv/app/reports/assets /srv/app/reports/report.html /srv/app/reports/report.pdf
Adjust the paths to your actual filesystem. If your version or packaging behaves differently, consult the manual for that installed binary and inspect the exact command the PHP wrapper invokes.
Enabling local-file access globally is not a safe default for user-supplied HTML. The wkhtmltopdf project warns against using the tool with untrusted HTML because unsanitized HTML or JavaScript can put the server at risk. Keep input trusted and sanitized, and use the narrowest path allowance that works.
Check image loading and resource errors
Images are enabled by default in the documented command manual, but an option supplied by your application or wrapper may disable them. Look for --no-images; remove it or explicitly enable images with --images. Do not assume an image-rendering limitation before checking the effective options.
Rank #3
- Perfect Adobe Acrobat Pro alternative – lifetime license for Windows 10 and 11.
- EDIT text, images, pages, hyperlinks, designs in PDF documents. ORGANIZE PDFs.
- READ and Comment on PDFs – Intuitive reading modes & document commenting and mark up tools!
- CREATE, COMBINE, SCAN and COMPRESS PDFs.
- FILL forms & Digitally Sign PDFs. Work with Digital certificates
The manual also documents --load-media-error-handling and --load-error-handling. These govern what the converter does when resources fail; changing them can make a failure more visible or allow conversion to continue, but it will not correct a wrong path, denied permission, or unreachable URL. Treat them as diagnostic or output-policy settings, not as image fixes.
If an image is added to the page by JavaScript, make sure it exists before capture. The manual documents a JavaScript delay default of 200 milliseconds; a longer delay may help if timing is genuinely the problem. It will not fix a script error, a blocked request, or a URL that the renderer cannot access.
Verify the PHP wrapper and executable
Confirm that the executable installed on the server is the one you expect and that PHP can run it. If wkhtmltopdf is not on the process PATH, configure the wrapper’s documented binary setting with the full executable path. A shell session and a PHP-FPM or web-server process may have different environment variables and permissions.
Recommended Free Tools
A minimal wrapper flow, using the package’s Pdf constructor and documented saveAs() and getError() methods, looks like this:
Rank #4
![PDF Extra 2024| Complete PDF Reader and Editor | Create, Edit, Convert, Combine, Comment, Fill & Sign PDFs | Lifetime License | 1 Windows PC | 1 User [PC Online code]](https://m.media-amazon.com/images/I/41eZq4aiipL._SL160_.jpg)
- EDIT text, images & designs in PDF documents. ORGANIZE PDFs. Convert PDFs to Word, Excel & ePub.
- READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.
- CREATE, COMBINE, SCAN and COMPRESS PDFs
- FILL forms & Digitally Sign PDFs. PROTECT and Encrypt PDFs
- LIFETIME License for 1 Windows PC or Laptop. 5GB MobiDrive Cloud Storage Included.
<?php
$pdf = new mikehaertlwkhtmltoPdf('/srv/app/reports/report.html');
if (!$pdf->saveAs('/srv/app/reports/report.pdf')) {
throw new RuntimeException($pdf->getError());
}
?>
This example assumes the package’s class is available through your application’s autoloader and the executable is discoverable. If it is not, set the wrapper’s binary configuration to the actual path using the configuration form supported by the package version you have installed. Do not assume that a successful PHP return means every image loaded: inspect the PDF and the converter’s warnings or standard-error output as well.
Diagnose remote images and HTTPS failures
- Copy the exact image URL. Test the final URL after any redirects from the conversion host, not from a developer laptop.
- Check access requirements. Confirm that the image does not require a logged-in browser session, a cookie, or authorization headers that the renderer does not have.
- Check network and proxy settings. Verify name resolution, outbound connectivity, firewall rules, and any proxy configuration relevant to the renderer.
- Inspect TLS and the deployed build. Check certificate-chain validity and the actual
wkhtmltopdfversion and packaging used in production. - Read warnings and inspect output. A generated PDF may be incomplete even if the wrapper reports that it saved the file.
HTTPS is not established as universally unsupported by an individual issue report. One user described HTTPS CSS and images failing with wkhtmltopdf 0.12.4 on Apache, Debian 9, and PHP 7.3, while HTTP worked in that environment. That is an environment-specific report, not a general compatibility rule or a universal fix. Investigate the actual endpoint, certificate chain, build, and logs.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsUse a short decision path
- Local HTML file and local image: resolve the relative path from the HTML file’s directory, verify case and read permissions, then use a narrow
--allowpath if local-file restrictions prevent access. - HTML string and relative image: establish a valid base context or replace the reference with a path or URL that the renderer can resolve.
- Remote image: test access from the conversion host and check redirects, authentication, proxy, DNS, and TLS.
- JavaScript-created image: confirm the image is inserted before rendering; adjust delay only when the evidence points to timing.
- Everything appears correct but the PDF is still wrong: check the exact binary, wrapper configuration, effective options, standard error, and generated PDF.
Common errors and what to change
| Symptom | Likely check | Next action |
|---|---|---|
| Local image missing, remote image present | Local-file access restriction or path mismatch | Resolve the path from the supplied input and allow only the required asset directory. |
| Image works on a laptop but not on the server | Different filesystem, permissions, network, or environment | Test from the converter’s host and account; compare the deployed binary and effective options. |
| Only JavaScript-loaded images are missing | Rendering happens before the image is inserted | Check browser-console-equivalent logs and page timing; increase delay only if timing is confirmed. |
| PDF is created without a visible error, but image is blank | Successful file creation is being mistaken for successful resource loading | Inspect warnings or standard error and open the output PDF. A macOS user reported this symptom with wkhtmltopdf 0.12.6 with patched Qt; it does not establish that build as generally faulty. |
| HTTP works but HTTPS does not | Endpoint, certificate chain, renderer build, proxy, or environment | Investigate those specifics; do not infer that HTTPS is always unsupported. |
| CSS and images both fail | Shared base path or resource-access problem | Check the document base and local-file policy before debugging each asset independently. |
Version and reliability considerations
The project’s downloads page identifies 0.12.6 as the stable release and gives June 11, 2020 as its release date. That is a dated project statement, not proof that every current distribution installs that build. Check the version reported by the executable in your deployed environment; packages may differ, and reports tied to 0.12.4 or a particular patched-Qt build should not be generalized to every installation.
Best Value
- Full-featured PDF Editor: Edit text in the document
- Fully convert PDF to Word and Excel and continue editing
- NEW: Further development of existing functions
- NEW: Even faster and more user-friendly
- NEW: Over 75 small improvements in all areas
For repeatable PDF generation, run conversion under the same service account and environment used in production, keep asset paths deterministic, and capture converter warnings alongside application logs. When remote resources are involved, document whether the renderer must use a proxy or credentials. These checks help distinguish an asset problem from a binary or environment problem without masking failures through permissive error handling.
Or skip the browser setup
If your goal is a clean screenshot or a PDF capture rather than debugging a local renderer, ScreenshotNeo is a website screenshot API and MCP server for developers. Its HTTP API accepts a URL and can return an image or PDF; it handles browser setup on the service side. The code below saves a PDF response for a page URL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -d format=pdf -o page.pdf
See the ScreenshotNeo documentation for API options and setup. Cookie/consent banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000. Sign up for free and try ScreenshotNeo.
What to include when asking for help
If the cause is still unclear, share a minimal sanitized example with the exact input type (local filename, HTML string, or URL), one failing image reference, the output from wkhtmltopdf --version, the operating system or container, and relevant wrapper options and warnings. Do not include secrets, private URLs, or untrusted HTML. That information makes it possible to distinguish a path problem from a resource policy, network failure, or build-specific issue.
Frequently Asked Questions
Does a browser preview prove that wkhtmltopdf can load the image?
No. The renderer runs in the conversion environment, which may not share the browser’s filesystem, network access, credentials, or permissions.
Is there a known percentage of broken images caused by local-file access?
No defensible cause-rate is established in the cited project documentation and issue reports.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
