The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Yes, wkhtmltopdf can still write a PDF when an image fails. First determine whether images were disabled, inaccessible, loaded too late, or hidden by print CSS. Keep image loading enabled, fix the resource path or access policy, and use --load-media-error-handling ignore (or skip) when incomplete output is acceptable. That setting controls the response to a failed media request; it does not make a missing image valid.
Start with a reproducible command
Save the exact command, input type, operating system, package source and version before changing several variables at once. Run:
wkhtmltopdf --version
wkhtmltopdf --images --load-media-error-handling ignore input.html output.pdf--images is the documented default, but an option added by a wrapper, framework or configuration file can override what you intended. Inspect the final command actually executed. If the command still aborts, also test the page-level policy:
wkhtmltopdf --images
--load-error-handling ignore
--load-media-error-handling ignore
input.html output.pdfUse --load-error-handling ignore cautiously: it applies to page-load failures, not just images. A PDF produced this way may be incomplete.
Recommended Free Tools
#1 Best Overall
1. Confirm that wkhtmltopdf is allowed to load images
Check for --no-images
The upstream command reference documents --images as loading or printing images by default and --no-images as disabling them. Remove --no-images from the assembled command and add --images explicitly while diagnosing. Some wrappers expose a boolean such as loadImages; verify its generated CLI equivalent rather than only the wrapper’s source setting.
Inspect stderr
Capture diagnostics so a failed URL or file path is not lost in application logs:
wkhtmltopdf --images input.html output.pdf 2>wkhtmltopdf.stderr
cat wkhtmltopdf.stderrRecord the first failed resource, redirects, certificate errors and permission messages. The exact error text, HTML and build are needed to distinguish a bad path from a network or rendering problem.
2. Fix local HTML and local-image paths
Resolve relative URLs from the document location
In a local document, <img src="images/logo.png"> is resolved relative to the HTML file’s directory, not necessarily the process’s current working directory. Confirm that the file exists at the resolved location. An absolute file URL can make the intended location explicit, but it must use a correctly formatted path for the operating system.
mkdir -p /tmp/pdf-test/images
cp logo.png /tmp/pdf-test/images/logo.png
cp input.html /tmp/pdf-test/index.html
wkhtmltopdf /tmp/pdf-test/index.html /tmp/pdf-test/output.pdfTest with a simple known-good image before debugging a complex page. Check filename case, URL-encoding for spaces or non-ASCII characters, symlinks, and whether the converter account can read every parent directory.
Handle local-file access deliberately
The upstream usage reference documents --disable-local-file-access as the default policy in relevant builds, plus --enable-local-file-access and --allow. Prefer the narrowest allowance:
wkhtmltopdf --allow /srv/site/assets /srv/site/index.html output.pdfIf the document genuinely needs broader access, test:
wkhtmltopdf --enable-local-file-access /srv/site/index.html output.pdfDo not broadly enable local-file access for untrusted HTML. The project’s security guidance warns against rendering untrusted HTML and recommends sanitizing user-supplied HTML and JavaScript; it also describes mandatory access controls such as AppArmor as a filesystem backstop on supported Linux systems. Treat an HTML-to-PDF worker as a privileged boundary: run it with a restricted account, limit readable directories and isolate temporary files.
3. Test remote image URLs from the converter’s machine
A browser on your laptop reaching an image does not prove that the wkhtmltopdf process can reach it. From the same host or container, check the exact URL and its final redirect. Verify:
- DNS resolution and outbound firewall rules;
- proxy settings and whether the process inherits them;
- TLS certificates and system clock;
- authentication headers, cookies or signed URL expiry;
- redirect destinations and hotlink or referer restrictions; and
- the image response’s status, content type and nonzero body.
The command reference includes proxy and custom-request options. Apply them only when the target requires them, and avoid placing long-lived credentials in shell history. If an image is private, supply the same authentication mechanism the page expects and confirm that redirects preserve it.
4. Choose the right failure policy
| Option | Documented default | Use | What it cannot do |
|---|---|---|---|
--load-error-handling |
abort |
Controls page-load failures; choices are abort, ignore and skip. |
It does not repair an inaccessible image. |
--load-media-error-handling |
ignore |
Controls failed media such as images; choices are abort, ignore and skip. |
It only decides whether conversion continues or media is skipped. |
For a report where missing artwork is acceptable, --load-media-error-handling ignore is usually the least disruptive test. Use abort when an incomplete PDF must never be delivered. Use skip when you want failed media omitted while continuing, according to the behavior of your build. Always inspect stderr and validate the resulting PDF; a zero exit status does not establish that every image rendered.
5. Wait for JavaScript-generated images
JavaScript is enabled by default, and the documented default delay is 200 milliseconds. A page that inserts <img> elements after an API call can therefore be captured before the elements or their sources exist.
Use a measured delay
wkhtmltopdf --enable-javascript --javascript-delay 1500 input.html output.pdfIncrease the delay only after confirming that the page becomes complete later. A longer fixed wait slows every job and still fails when a request is slower than expected.
Prefer an explicit readiness marker
If you control the page, set a predictable window status after all images are inserted and usable:
<script>
Promise.all([...document.images].map(img => img.complete
? Promise.resolve()
: new Promise(resolve => { img.onload = img.onerror = resolve; })))
.then(() => { window.status = 'pdf-ready'; });
</script>Then coordinate conversion with:
wkhtmltopdf --window-status pdf-ready input.html output.pdfTest this against the actual page. The option is useful only when the page reliably sets the requested status; it is not a universal fix for blocked requests.
Rank #4
6. Compare screen and print media
wkhtmltopdf uses screen media by default. --print-media-type switches to print media, which can activate rules that hide images, change display, replace backgrounds or alter generated content.
wkhtmltopdf input.html screen.pdf
wkhtmltopdf --print-media-type input.html print.pdfInspect @media print rules for display:none, visibility:hidden, zero dimensions, background-image usage and selectors that target the image container. Check the generated DOM if JavaScript is involved. An open issue reported missing images with --print-media-type on wkhtmltopdf 0.12.6 patched Qt on macOS 12.6.1. That is an environment-specific report, not proof of a universal defect; treat it as a reason to compare both modes and record the build.
7. Record build and platform differences
The official download information identifies stable series 0.12.6, released June 11, 2020, and warns that distributions can diverge. Patched-Qt features, system libraries and fonts affect rendering. Debian Bullseye’s manpage identifies its package as built against Qt without wkhtmltopdf patches and notes reduced functionality.
Include these fields in every bug report:
- output of
wkhtmltopdf --version; - operating system, container image and CPU architecture;
- package source or downloaded binary;
- the complete command and wrapper-generated flags;
- HTML, image URLs or paths and whether they are trusted; and
- stderr output and whether screen mode differs from print mode.
Do not assume a command copied from a patched binary behaves identically on a distribution build.
A compact diagnostic decision tree
- No images anywhere: remove
--no-images, add--images, and inspect stderr. - Only local images fail: resolve paths from the HTML file, verify permissions, then use a specific
--allowdirectory or, only for trusted input,--enable-local-file-access. - Only remote images fail: test the exact URL from the converter host, including DNS, proxy, TLS, redirects and credentials.
- PDF is required despite one failed image: select the documented media policy that matches your quality requirement, usually
ignoreorskip, and mark the output as potentially incomplete. - Images appear in a browser but not in the PDF: test a measured JavaScript delay, then a reliable
--window-statusmarker. - Images vanish only with print mode: inspect print CSS and compare builds before changing unrelated network settings.
Performance, reliability and safety trade-offs
- Delays: improve the chance of catching asynchronous content but increase latency for every conversion.
- Broad file access: can make local assets work quickly but expands the damage possible from untrusted HTML; a narrow
--allowpath is safer. - Ignore or skip: keeps pipelines moving but can publish a document missing branding, charts or legally required material. Add a post-conversion check when image completeness matters.
- Remote assets: add DNS, network and third-party availability dependencies. For repeatable jobs, use controlled asset hosting and explicit timeouts in the surrounding worker.
- Build choice: patched and distribution packages may differ in features and rendering, so pin and document the binary used in production.
Or skip the browser setup
If your goal is simply a clean screenshot or PDF of a web page rather than debugging a wkhtmltopdf job, ScreenshotNeo provides a website screenshot API and MCP server. Its capture pipeline accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups and chat widgets before the shot. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers report the page verdict and billing status.
Free tools Windows power users keep installed
One-click scans. No signup required.
One GET request is enough:
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 options such as full-page capture, a CSS-selected element, device and retina settings, PDF output, custom JavaScript and CSS, request blocking, cookies and headers, network-idle waits, signed links, asynchronous webhooks and bulk capture. An MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.
Python:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to try it.
FAQ
Will --load-media-error-handling ignore recreate a broken image?
No. It changes whether conversion continues after media loading fails. The image remains unavailable unless its path, access, network response or rendering timing is fixed.
Is --enable-local-file-access safe for user-submitted HTML?
Not by itself. It broadens what the renderer may read. Sanitize untrusted HTML and isolate the process with least-privilege filesystem controls instead.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Why does a distribution package behave differently from a downloaded binary?
wkhtmltopdf builds can use different Qt patches and system libraries. Record the package source and version, then reproduce the issue with the same build before changing configuration.
Frequently Asked Questions
Can I make wkhtmltopdf substitute a placeholder for a missing image?
The documented load-error options control continuation, not image substitution. Add a fallback in the HTML or preprocessing pipeline if a visible placeholder is required.
Should I always use print media for PDF output?
No. Screen media is the default. Use print media only when your stylesheet is designed for it, and verify that its rules do not hide or resize the images.
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.
