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 appear in your HTML but disappear from a PDF generated with WkHtmlToXSharp, first check whether the converter process can read each image and whether image loading is enabled. A browser rendering the page successfully does not prove that the separate PDF-conversion process can access the same files. Check the actual wrapper and wkhtmltopdf versions, local-file permissions, and the image-loading setting before changing formats or rewriting paths.
Why images can appear in HTML but not in the PDF
HTML rendering and PDF conversion may run in different contexts. The converter may have a different working directory, filesystem permissions, network access, or runtime environment from the browser or application that produced the HTML. A relative path that works on a website can therefore fail when the wrapper passes the document to wkhtmltopdf.
Two controls are especially easy to confuse: whether the converter is allowed to read local files, and whether it is configured to load images at all. The wkhtmltopdf usage documentation lists --images as loading or printing images, enabled by default, and documents local-file access controls including --allow for permitted paths. The libwkhtmltox settings reference separately defines web.loadImages.
Free tools Windows power users keep installed
One-click scans. No signup required.
These controls and their wrapper equivalents depend on the deployed version. Start with the converter process and its configuration rather than assuming a single path change will fix every case.
#1 Best Overall
Identify the versions and the kind of image
Before changing settings, record what is actually running. WkHtmlToXSharp is a wrapper; its own version and the wkhtmltopdf library or executable it uses both matter. Also note the operating system and whether the wrapper receives an HTML string or a saved HTML file.
- Wrapper version and embedded or installed wkhtmltopdf version.
- Operating system and the account or service identity running conversion.
- Whether the HTML is passed as a string or read from disk.
- Whether the failing image is remote (an HTTP/HTTPS URL) or local (a filesystem path or file URL).
- Whether the image is present in the original HTML or inserted later by JavaScript.
The distinction helps narrow the next test. A remote image points toward URL reachability, authentication, or loading behavior; a local image points toward path resolution and local-file access. If the image is generated or inserted dynamically, a timing issue is possible, but the cited documentation does not establish that as the cause in any particular deployment.
Check the image URL or filesystem path as the converter sees it
For remote images
Use a complete URL with the correct scheme and host, and confirm that the machine running PDF conversion can reach it. A URL that loads in a developer’s browser might rely on a logged-in session, local network access, or credentials not present in the conversion process. If the page requires authentication, determine whether the wrapper can supply the necessary request context; do not assume a browser’s existing cookies are reused.
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 →For local images
Resolve the path from the converter’s runtime environment. Relative paths depend on a base location, which may differ between an HTML string, a saved file, and a service process. Confirm that the file exists at the resolved location and that the conversion account can read it. Use the path form supported by your operating system and wrapper; filesystem path syntax and file URLs are not interchangeable in every context.
Rank #2
An absolute path can help clarify which file is intended, but it is not a guaranteed fix. A directly relevant WkHtmlToXSharp question reported that changing a relative image path to an absolute one still did not make the image appear. That result is a reminder to check permissions and converter settings as well as the path itself.
Allow the required local files safely
When a local image is blocked, check the converter’s local-file access policy. The wkhtmltopdf usage documentation describes local-file access restrictions and an --allow option for explicitly permitted paths. For a wrapper, find the equivalent option in the version you actually deploy and allow only the directory needed for the conversion.
Do not copy a setting name from a different wrapper without verifying that WkHtmlToXSharp supports it. For example, an issue report for WkHtmlToPdf-DotNet describes its author fixing a case associated with wkhtmltopdf 0.12.6 by setting that wrapper’s BlockLocalFileAccess property. This is evidence about that wrapper and reported case, not proof that WkHtmlToXSharp exposes the same property or that the same change is appropriate everywhere. Check your wrapper’s API and bundled converter version before applying an equivalent setting.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Granting broad filesystem access can expose files the conversion process does not need. Prefer a narrow asset directory, and ensure the service identity has read permission for that directory and its files.
Rank #3
- hole punched
- high quality card stock
- 4 pages
- made in USA
- keyboard shortcuts
Verify that image loading has not been disabled
Check the wrapper configuration for an image-loading option. In the libwkhtmltox interface, the setting is named web.loadImages and accepts "true" or "false". If the wrapper sets it to false, images will not be loaded even when their paths are valid. If no explicit override is present, confirm the default behavior for the converter version you deploy rather than relying on a default from another release.
Keep this check separate from local-file access: enabling image loading does not automatically grant permission to read a local file, and allowing local files does not turn image loading on if it has been disabled.
Reduce the problem with a minimal test
- Create a small HTML input with one image and minimal layout. Use the same input method as the failing conversion: if production supplies an HTML string, test an HTML string; if it supplies a file, test a file.
- Use an image URL or local image whose location and accessibility you can verify from the conversion environment.
- Run the test through the same wrapper, operating-system account, and converter version as the failing job.
- Inspect converter output and wrapper diagnostics for failed resource loads or access errors, where available.
- Change one factor at a time: path form, local-file access, image-loading setting, then any timing behavior relevant to generated content.
If the minimal input works but the production document does not, compare the production HTML, base location, resource paths, and runtime conditions. That points the investigation toward the document or its dependencies rather than a general inability to render images.
Recommended Free Tools
Try format changes only after access checks
If the same reachable image fails while other images load, compare it with a PNG or JPEG copy as a controlled test. One 2011 answer to a WkHtmlToXSharp question suggested trying GIF images as JPEG or PNG, but the available evidence does not establish a universal GIF limitation or a current format guarantee. Treat conversion as a diagnostic branch, not the default fix. If another format works, investigate the particular image and converter version before changing all assets.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot by symptom
| Symptom | Likely area to check | Next action |
|---|---|---|
| All local images are missing, but text renders | Local-file access policy, service-account permissions, or path resolution | Verify the resolved paths and reader permissions; check the version-specific equivalent of the documented local-file access controls. |
| Only images with relative paths are missing | Base location differs between browser and converter | Test with a correctly resolved path for the actual input method and runtime; do not stop at changing to an absolute path if access is still blocked. |
| Remote images are missing | Converter network reachability, URL, authentication, or image loading disabled | Verify the URL from the conversion environment and inspect image-loading configuration. |
| Images disappear after a wrapper or converter upgrade | Changed defaults, supported settings, or bundled converter version | Record both versions and compare the current wrapper API and converter settings with the prior deployment. |
| One image format fails while others work | Potential image-specific or format-specific issue | Test a PNG or JPEG copy while holding the path and settings constant; do not infer a general format limitation from one result. |
| Static images work but generated ones do not | Possible timing or JavaScript-dependent content | Test whether the image exists in the HTML at capture time and check the wrapper’s documented wait behavior, if available. |
Or skip the browser setup
If your goal is simply to obtain a clean screenshot of a webpage rather than generate a PDF through WkHtmlToXSharp, ScreenshotNeo offers a one-request screenshot API. It returns a PNG, JPEG, WebP, or PDF. For example, this cURL request saves a WebP screenshot of a page; see the ScreenshotNeo documentation for request options:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
- It accepts cookie or consent banners before capture and removes 60+ known consent platforms, newsletter popups, and chat widgets; each step can be turned off.
- Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and whether the request was billed.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for Claude, Cursor, and other MCP clients. - The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month with no card.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteFrequently Asked Questions
Does making an image path absolute always fix missing PDF images?
No. It can clarify the intended location, but it does not resolve blocked local-file access, missing permissions, or disabled image loading.
Is GIF unsupported by WkHtmlToXSharp?
The available evidence does not establish a universal GIF limitation. Comparing a PNG or JPEG copy is a diagnostic test, not a compatibility guarantee.
Does the WkHtmlToPdf-DotNet BlockLocalFileAccess setting apply to WkHtmlToXSharp?
Not on the evidence available. That setting is reported for a different wrapper; check WkHtmlToXSharp’s own API and the deployed converter version.
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.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →
