Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsThe usual fix is to check four independent controls: image loading, permission to read local files, path resolution under the account running wkhtmltopdf, and JavaScript timing. A browser preview proves only that your browser can fetch the image; it does not prove that the converter can see the same path or that the image exists when PDF rendering starts.
Use the checklist below with the exact executable, wrapper, user account and input that produce the bad PDF. Start with a minimal one-image file, change one setting at a time, and keep local-file access as narrow as possible.
Why an image can work in HTML but disappear from the PDF
A browser and wkhtmltopdf are different processes with different security policies, working directories, network access and rendering clocks. The browser may resolve a relative URL from the page address, while a conversion job reading a local file resolves it from that file’s directory. A browser session may also have permission to read your desktop files that a service account, container or AppArmor profile does not.
The image can therefore fail at several separate points:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
- BEST FOR SMALL BUSINESSES – Engineered for extraordinary productivity, the Brother DCP-L2640DW Monochrome (Black & White) 3-in-1 combines laser printer, scanner, copier in one compact footprint and delivers high-quality black & white prints
- FAST PRINTER WITH EFFICIENT SCANNING – Produces documents quickly with print speeds up to 36 ppm(2) and scan speeds up to 23.6/7.9 ipm(3) (black/color). A 50-page auto document feeder(4) allows for convenient, time saving multi-page scanning and copying
- FLEXIBLE CONNECTION OPTIONS – Easily navigate the changing demands of your business with secure multi-device connectivity via built-in dual-band wireless (2.4GHz / 5GHz) and Ethernet. Or connect locally to a single computer via USB interface
- BROTHER MOBILE CONNECT APP – Print, scan, and manage your wireless printer anytime, from almost anywhere from your mobile device. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(5)
- CHOOSE BROTHER GENUINE TONER – When it’s time to replace your toner, be sure to choose Brother Genuine TN830 or TN830XL replacement toner. And with Refresh EZ Print Subscription Service, you’ll never worry about running out of toner again and you’ll enjoy savings of up to 50%(6) on Brother Genuine Toner. Get started with Refresh today with a Free Trial(1)
- Loading is disabled. The command-line option
--no-imagessuppresses images; image loading is otherwise documented as enabled by default. - Local-file access is blocked. Reading the HTML file does not automatically grant permission to read nearby image files.
- The path resolves somewhere else. Relative paths, Windows drive letters, URL encoding and the converter’s current directory can all change the result.
- The process cannot read the asset. File ownership, mode bits, ACLs, a container mount or a mandatory-access-control profile can block the account that runs the job.
- The image is created late. JavaScript may insert the
imgelement or set itssrcafter the initial document load. - A media error is being hidden. A permissive media-error policy can let conversion finish while silently skipping a failed resource.
Issue reports show this symptom in real projects, but they do not establish one universal fix. Treat each control independently and record the effective settings produced by your wrapper.
First response: a fast, repeatable diagnostic
- Capture the exact invocation. Log the full wkhtmltopdf command (with secrets removed), the executable path, version, input type and output path. A library or framework may add arguments that are not visible in application code.
- Make a one-image reproduction. Create an HTML file containing one image and no JavaScript, stylesheets or framework code. Run it with the same user, container, mounts and command used by the failing job.
- Classify the image URL. Test a remote
https://URL and a local file separately. For a local file, write down the absolute path obtained after resolving the HTML document’s base location. - Check stderr and exit status. Preserve warnings about failed loads. During diagnosis, do not hide them with an ignore policy.
- Change one variable. Test image loading, then path and permissions, then local-file policy, then JavaScript timing. This identifies the failing layer instead of producing a command that happens to work by accident.
Step 1: verify that image loading is enabled
Inspect the command line generated by your wrapper. The wkhtmltopdf CLI documents --images as the setting that loads or prints images and --no-images as the switch that disables them. If your command contains --no-images, remove it or replace it with the image-loading setting required by your integration.
Library users should inspect the effective web.loadImages value, not only a configuration file. Framework defaults, environment-specific profiles and per-job overrides can change it. Re-run the minimal file after confirming the value; do not infer success from the browser preview.
Step 2: determine how the path is resolved
Local HTML input
For an input such as /srv/app/report.html and <img src="images/logo.png">, the intended asset is normally /srv/app/images/logo.png. Verify that this exact file exists from the conversion process’s environment. A service running in a container may see a different filesystem from your interactive shell.
Remote HTML input
When the input is an HTTP(S) URL, a relative image URL is resolved by the page’s URL, not by your local project directory. Check redirects, authentication, DNS, proxy rules and TLS access from the conversion host. If the image requires a cookie, authorization header or a private network route, the browser session that you tested may have credentials the converter does not.
Platform-specific path details
Use a valid path or URL form for the operating system and wrapper. Check drive letters and backslashes on Windows, URL encoding for spaces and non-ASCII characters, and case sensitivity on Linux. Avoid guessing a “portable” syntax: the documented controls establish that local-file access exists, but path handling can vary by platform, build and integration.
Rank #2
- BEST FOR HOMES & HOME OFFICES – Engineered for consistent, premium print quality, the Brother HL-L2405W Monochrome (Black & White) Laser Printer delivers sharp, crisp prints at an affordable price. Prints one-sided documents at speeds up to 30ppm(2)
- COMPACT, CONNECTED PRINTER – Flexible connection options make this an ideal printer for home use and at-home offices. Securely connect to multiple devices with built-in dual-band wireless (2.4GHz/5GHz) or locally to a single computer via USB interface
- BROTHER MOBILE CONNECT APP – Manage your printer remotely and print from your mobile device anytime, from almost anywhere. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(3)
- VERSATILE PAPER HANDLING – Enjoy seamless, reliable everyday printing with the 250-sheet paper tray(4) and a manual feed slot that enables printing on envelopes and specialty pape
- BROTHER IS AT YOUR SIDE – Backed by Brother with a 1-year limited warranty and free online, call, or live chat support for the life of your printer
Step 3: allow only the local files you need
wkhtmltopdf separates image loading from local-file permissions. Its CLI documents --disable-local-file-access and --enable-local-file-access; local files can otherwise be explicitly permitted with one or more --allow paths. The library setting load.blockLocalFileAccess exposes the same policy in integrations.
Grant the smallest directory that contains the intended assets. For example, if a report uses files below /srv/app/report-assets, allow that directory rather than the entire filesystem. A broad exception may make a test pass while exposing secrets to untrusted HTML. The command-line documentation describes the rule this way: “Do not allowed conversion of a local file to read in other local files, unless explicitly allowed with –allow.”
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
After changing the policy, run the minimal reproduction under the production account. If it works only with unrestricted access, stop and narrow the allowed path before deploying.
Step 4: prove that the conversion account can read the asset
Run an existence and read test as the same operating-system account that launches wkhtmltopdf. Check every parent directory, not just the image’s mode bits: a directory needs execute (traverse) permission, and a container needs the directory mounted inside its namespace. Also check ACLs, SELinux or AppArmor rules, read-only mounts and temporary-file cleanup.
If a web request creates the image, make sure conversion starts after the file is flushed and that the path remains valid for the entire job. Prefer a stable, absolute asset location for server-side rendering. Do not “fix” a permission failure by making an entire application tree world-readable.
Step 5: make media failures visible
The CLI documents --load-media-error-handling with abort, ignore and skip behaviors. During diagnosis, choose a policy that surfaces a failed image and review stderr; an ignore policy can produce a PDF that looks successful but has missing media. Exact warning text varies by build and wrapper, so record the executable version and the complete stderr output.
Rank #3
- FAST PRINT SPEEDS: Print up to 19 pages per minute.
- COMPACT DESIGN: Space-saving, compact design fits anywhere in your home, school or small office.
- WIRELESS CONNECTIVITY: Print from almost anywhere in your workspace using your compatible mobile device.
- PAPER CAPACITY: Up to 150 sheets.
- SUSTAINABILITY: Uses less than 2 watts in Energy Saver mode.
Once the cause is fixed, choose the production policy deliberately. Aborting is appropriate when an image is mandatory; skipping may be acceptable for optional decoration. Whichever policy you choose, monitor exit status and retain enough logs to distinguish a missing image from a successful conversion.
Step 6: handle JavaScript-created images and timing
Confirm JavaScript is enabled
If a script inserts the image element, assigns src, swaps a low-resolution placeholder or renders a canvas, confirm that JavaScript is enabled in the effective settings. A static test image is useful here: if it appears but the scripted one does not, the problem is probably timing or script compatibility rather than file access.
Wait for the real readiness condition
wkhtmltopdf documents a JavaScript-delay control, and library integrations expose JavaScript and delay settings. Use a delay long enough for your application and verify it under normal load; an arbitrary delay is only a workaround and can be flaky when the network or server is slow. Where your wrapper supports waiting for a page condition, wait until the image has loaded or your application sets a ready marker, then capture.
Separate script errors from image errors
Enable the wrapper’s JavaScript diagnostics where available and inspect browser-console output. A script exception, blocked third-party request or cross-origin restriction can prevent src from ever being assigned. Reproduce with a plain static <img> before changing delay values.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Useful command-line test patterns
These examples illustrate the controls; substitute your own paths and use the same binary as production.
wkhtmltopdf --images --disable-javascript /srv/app/test.html /tmp/test.pdfUse the first test to remove JavaScript as a variable. If the static image is still absent, test the local-file policy explicitly:
Rank #4
- BEST FOR HOME OFFICES & SMALL TEAMS – Engineered for consistent, premium print quality, the Brother HL-L2460DW Monochrome (Black & White) Laser Printer produces documents that are clear, crisp, and easy to review and share, all at an affordable price
- COMPACT, CONNECTED, EXCEPTIONALLY EFFICIENT– Connect with built-in dual-band wireless (2.4GHz/5GHz), Ethernet, or to a single computer via USB interface. Prints at speeds up to 36ppm(2), plus automatic duplex printing saves time and reduces paper waste
- BROTHER MOBILE CONNECT APP – Manage your wireless printer remotely and print from your mobile device anytime, from almost anywhere. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(3)
- VERSATILE PAPER HANDLING – Tackle high-volume black & white printing with the 250-sheet capacity paper tray.(4) The manual feed slot enables printing on envelopes and specialty paper
- BROTHER IS AT YOUR SIDE – Backed by Brother with a 1-year limited warranty and free online, call, or live chat support for the life of your printer
wkhtmltopdf --images --enable-local-file-access --allow /srv/app/report-assets /srv/app/test.html /tmp/test-local.pdfIf the asset is generated by JavaScript, enable scripting and add a delay appropriate to the application:
wkhtmltopdf --images --enable-javascript --javascript-delay 1500 /srv/app/dynamic.html /tmp/test-dynamic.pdfKeep stderr visible while testing. If your wrapper sets a media-error policy, configure it explicitly rather than relying on a hidden default.
CLI flags versus library and wrapper settings
The names differ, but the diagnostic questions are the same. Map your integration’s settings to these controls before debugging:
| Question | CLI documentation term | Library or wrapper term | What to verify |
|---|---|---|---|
| May images load? | --images / --no-images |
web.loadImages |
The effective value for this job |
| May local files be read? | --enable-local-file-access, --disable-local-file-access, --allow |
load.blockLocalFileAccess |
Whether the exact asset directory is permitted |
| How long does rendering wait? | JavaScript delay option | JavaScript enablement and delay settings | That the image is ready before capture |
| What happens on media failure? | --load-media-error-handling |
Wrapper-specific error policy | Whether failures are surfaced, skipped or ignored |
Do not assume a setting in source code survived argument generation. Log the final argument list or inspect the integration’s debug output.
Security: do not trade a missing image for filesystem exposure
Converting untrusted HTML with broad local-file access can expose files that the HTML was never meant to read. The project’s AppArmor guidance describes restricting filesystem access; apply the same principle to containers, service accounts and operating-system permissions.
- Use a dedicated conversion account with no access to application secrets.
- Allow only a temporary asset directory, and remove it after the job.
- Keep local-file access disabled for documents that do not need local resources.
- Validate or sanitize user-supplied HTML and reject unexpected URL schemes.
- Use network egress controls when remote resources are not required.
Symptom-to-cause troubleshooting table
| Symptom | Likely boundary | Next check |
|---|---|---|
| Every image is missing, including a known remote URL | Global image setting or network access | Remove --no-images, confirm web.loadImages, then test remote access from the converter host |
| Remote images work; local images do not | Local-file policy, path or permissions | Resolve an absolute path, test the conversion account, and use a narrow --allow directory |
| A local image works from a shell but not in the service | Different account, mount or security profile | Run the same read test inside the service/container and inspect AppArmor or similar rules |
| Static image works; generated image is missing | JavaScript or timing | Enable scripting, inspect script errors and wait for the image-ready condition |
| PDF exits successfully but has occasional missing images | Media errors being skipped or ignored | Review stderr and set an explicit media-error policy while diagnosing |
| Only images with spaces or non-ASCII names fail | URL encoding or platform path syntax | Test an encoded URL and an ASCII filename, then correct the path construction |
Reliability and performance practices
- Use deterministic inputs. Bundle required static assets with the job or serve them from a reachable, authenticated endpoint.
- Make readiness observable. Have the page set a ready marker after images finish loading instead of relying only on a large fixed delay.
- Keep a regression fixture. A tiny HTML file containing one local image, one remote image and one JavaScript-created image catches changes in wrappers or executable builds.
- Record environment details. Store the wkhtmltopdf version, operating system, wrapper version, flags, account, input kind and stderr with failed jobs.
- Choose failure semantics. Abort when a missing image invalidates the document; skip only when the image is optional and the omission is visible to downstream users.
- Limit unnecessary work. Loading a whole page, waiting for network activity and enabling scripts can increase render time. Prefer static assets and a readiness condition when possible.
Or skip the browser setup
If your goal is a clean screenshot or PDF of a reachable web page rather than a local-file wkhtmltopdf pipeline, ScreenshotNeo provides a single HTTP request. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.
Free tools Windows power users keep installed
One-click scans. No signup required.
cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
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}`);See the ScreenshotNeo API documentation for the parameters. The service supports PNG, JPEG, WebP and PDF output, full-page capture with lazy images loaded, CSS-selector element capture, dark mode, device presets or custom viewports, retina scale, custom CSS and JavaScript, click and wait actions, request blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, chosen-TTL caching, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API and an OpenAPI specification. An MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.
Best Value
- FROM AMERICA'S MOST TRUSTED PRINTER BRAND – Perfect for small teams printing professional-quality black & white documents and reports. Perfect for 1-3 people
- WORLD'S SMALLEST LASER IN ITS CLASS – Precision laser printing that fits anywhere
- FAST PRINT SPEEDS – Up to 21 black-and-white pages per minute single-sided
- WIRELESS WITH SELF-RESET – Helps you stay connected
- PRINT FROM ANY DEVICE – Wireless printing from any mobile device, PC or tablet. Works with Microsoft, Mac, AirPrint, Android, Chromebook and more
| Plan | Allowance | Price |
|---|---|---|
| Free | 1,000 shots/month | $0, no card |
| Starter | 3,000 shots | $5 |
| Growth | 15,000 shots | $15 |
| Pro | 60,000 shots | $39 |
| Scale | 250,000 shots | $99 |
| Business | 1,000,000 shots | $249 |
Every feature is included on every plan, and yearly billing gives two months free. Start with 1,000 free screenshots a month with no card.
When to ask for a case-specific diagnosis
Provide the wkhtmltopdf version and operating system, the exact invocation or wrapper settings, whether the HTML and image are local or remote, the resolved image URL, the conversion account, and the complete warnings or stderr. Also state whether the image is static or JavaScript-created and whether a minimal reproduction changes the result. Those details distinguish a blocked resource from a timing, path or policy problem without granting unnecessary filesystem access.
Frequently Asked Questions
Do issue reports identify one guaranteed fix for this symptom?
No. Reports demonstrate that the symptom occurs, but the documented controls cover several independent causes. Diagnose image loading, path resolution, local-file policy, permissions and timing separately.
Recommended Free Tools
Should I enable unrestricted local-file access permanently?
No. If local assets are required, permit only the intended directory and use a restricted conversion account. Broad access can expose files when HTML is untrusted.
Why does a permissive media-error setting make debugging harder?
An ignore or skip policy can let conversion finish while omitting the image. Use visible warnings and an explicit policy during diagnosis, then choose production behavior based on whether the image is mandatory.
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.
