Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsSome links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
When an SVG contains nested images but those images disappear in a wkhtmltopdf PDF, there is no single encoding switch that reliably fixes every case. First identify your wkhtmltopdf/Qt build, then test the SVG as an external <img>, inline markup, and (if used) <object> while verifying local-file permissions and every nested image URL. Historical reports show that changing the inclusion route can change the result, but may introduce other rendering errors.
Why a browser preview can work while wkhtmltopdf fails
wkhtmltopdf converts HTML with a bundled Qt WebKit engine, not the current Chromium or Firefox engine. The project status page says: “Qt 4 (which wkhtmltopdf uses) hasn’t been supported since 2015, the WebKit in it hasn’t been updated since 2012.” A modern browser rendering an SVG successfully therefore does not prove that your wkhtmltopdf binary supports the same SVG features. See the project home and project status.
Issue #2996 describes wkhtmltopdf 0.12.3 with patched Qt rendering an SVG through an HTML img while an embedded base64 JPEG remained invisible, even though Firefox and Chrome displayed it. The same report says that putting the SVG markup directly into HTML made the embedded images appear but damaged other elements. Issue #3762 reports blank SVGs loaded through object. These are specific historical environments, not a guarantee that every SVG or every release behaves the same way.
The practical fix is a controlled diagnosis: establish the exact binary, isolate the inclusion method, inspect nested resources, and then choose a workaround or renderer that survives your production document.
#1 Best Overall
![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.
1. Record the exact wkhtmltopdf build
Run:
wkhtmltopdf --versionSave the complete output, including whether it says “with patched qt.” The usage documentation identifies 0.12.6 with patched Qt, while issue #2996 used 0.12.3 with patched Qt; do not assume those builds are interchangeable. Also record the operating system, installation source, container image, and the user account that runs the conversion. A file readable in your shell may be inaccessible to a service account.
Keep the version output with your bug report and test artifacts. Reproduce the failure with the same binary used in deployment, not a developer laptop installation.
2. Build a minimal reproduction
Remove unrelated CSS, JavaScript, web fonts, filters and page content. Keep the SVG’s width, height and viewBox, then reduce it to one visible shape and one nested image. Change one variable per run so you can tell whether the failure comes from SVG parsing, resource access, or page layout.
Free tools Windows power users keep installed
One-click scans. No signup required.
External SVG through img
<!doctype html>
<html><body>
<img src="assets/graphic.svg" width="600" height="400" alt="Test graphic">
</body></html>Convert it with the same command used in production:
wkhtmltopdf --enable-local-file-access test.html test-img.pdfThe --enable-local-file-access switch permits access to local files. For a tighter policy, use --allow /absolute/path/to/assets and keep the SVG and nested files below that directory. The settings reference documents local-file controls and resource-load error handling.
Inline SVG
<!doctype html>
<html><body>
<svg width="600" height="400" viewBox="0 0 600 400" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<rect width="600" height="400" fill="#eee"/>
<image href="data:image/png;base64,REPLACE_ME" x="20" y="20" width="560" height="360" preserveAspectRatio="xMidYMid meet"/>
</svg>
</body></html>Inline markup is a diagnostic path, not a universal remedy. In issue #2996 it exposed the nested image but caused other page elements to render incorrectly. Check the entire PDF, including surrounding HTML, after trying it.
Rank #2
- Edit PDFs with Ease. Modify text, images, and layouts directly within your PDF documents.
- Convert & Organize. Export PDFs to Word, Excel, or ePub, and organize files with ease.
- Read & Annotate. Enjoy intuitive reading modes and powerful tools to comment, highlight, and mark up PDFs.
- Create & Manage PDFs. Create new PDFs, combine multiple files, scan documents, and compress for easy sharing.
- Fill & Sign Forms. Complete forms and digitally sign documents with secure e-signature tools.
object inclusion
<object type="image/svg+xml" data="assets/graphic.svg" width="600" height="400"></object>Because issue #3762 reports a blank result with object, test it only as a separate branch. A tag change can alter loading and sizing behavior; it does not establish support for the SVG features inside the file.
3. Inspect every nested image reference
Open the SVG as text and locate each <image> element. Check both modern href and legacy xlink:href attributes. Classify each value:
- Data URI: verify the media type and base64 payload are complete, with no line-wrapping or truncation introduced by a template.
- Relative URL: resolve it from the SVG file’s location, not from the HTML file or process working directory. Confirm case-sensitive path names on Linux.
- Absolute local path: confirm the conversion user can read it and that your local-file policy allows its directory.
- HTTP(S) URL: verify DNS, TLS, authentication and network access from the conversion host. A browser on your workstation may have cookies or proxy settings that wkhtmltopdf lacks.
Temporarily replace a nested image with a tiny known-good PNG. If that appears, restore the original resource and investigate its format, URL, or dimensions. If no nested image appears, test a plain SVG shape; this separates image loading from general SVG support.
4. Make resource failures visible
Use the load-error options documented in the settings reference rather than silently accepting a partial page. Depending on your wrapper and version, configure document and media load handling to abort, ignore, or skip failures; choose the strictest mode that still lets you collect useful diagnostics in development. Capture stderr and the process exit code in automation. A successful process does not necessarily mean every referenced image loaded if errors are being ignored.
When debugging local files, use absolute paths and a temporary directory with predictable permissions. Run the exact command as the service account, inside the same container or VM, and compare directory listings and file access. Remove the temporary broad permission after the cause is known.
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 minute5. Test the SVG features most likely to expose legacy limits
After the minimal image works, add complexity one feature at a time:
Rank #3
- 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.
- multiple nested images and different image formats;
- CSS selectors inside the SVG;
- masks, clipping paths, filters, gradients and blend modes;
- custom fonts and text shaping;
- external stylesheets or SVG fragments;
- large dimensions, unusual view boxes and preserve-aspect-ratio settings.
Keep a PDF from each step. If one feature causes disappearance, retain that smallest failing file as a regression fixture. Qt’s current vector-image documentation describes SVG capabilities in Qt 6, but it is background information, not a specification for wkhtmltopdf’s older bundled WebKit. See Qt vector image documentation.
Workarounds when the nested image still fails
Rasterize only the affected graphic
If vector editing is not required in the final PDF, convert the SVG with an SVG-capable renderer and use the resulting PNG or JPEG in your HTML. Render at the physical pixel dimensions needed by the PDF, then inspect text and thin lines at 100% zoom. Rasterization can remove unsupported filters or font behavior from wkhtmltopdf’s workload, but it sacrifices infinite scaling and may increase file size.
Inline the SVG carefully
Inlining can bypass a failing external-document path. Namespace declarations, dimensions and the original viewBox must remain intact. Audit the rest of the page because the issue #2996 report observed unrelated elements changing when SVG markup was inserted into HTML.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Serve assets through a controlled URL
For deployments where local-file policies are difficult to manage, serve the SVG and its images from an internal HTTP endpoint with stable URLs and explicit authentication. Test certificate validation, redirects and access from the production host. This changes the failure mode from filesystem policy to network availability, so log both.
Evaluate a maintained browser renderer
If representative documents depend on modern SVG filters, fonts, external references or JavaScript, compare a maintained browser-based renderer against your complete templates. Test CSS, headers, footers, page breaks, fonts, authentication and deployment size—not just the SVG. The wkhtmltopdf status page itself points toward newer browser engines, but migration suitability is application-specific.
Choosing an approach
| Approach | Vector fidelity | Operational trade-off | Best use |
|---|---|---|---|
| Keep external SVG and fix access | Preserves vectors if the legacy engine supports the content | Requires correct paths, permissions and load diagnostics | Simple SVG with missing or inaccessible nested assets |
| Inline SVG | Can expose nested images that fail as external documents | May alter surrounding HTML rendering; larger templates | Controlled templates where markup interaction is acceptable |
| Rasterize selected graphics | Raster output at chosen resolution | No infinite scaling; an additional conversion step | Stable appearance is more important than vector output |
| Change renderer | Potentially better support for modern SVG | Migration and deployment testing for all PDF behavior | Documents blocked by legacy WebKit limitations |
The cited issue reports provide no controlled benchmark between these choices. Decide using your own representative documents and production binary.
Rank #4
- 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
Troubleshooting checklist
The SVG is completely blank
- Confirm the file URL and MIME/type declaration.
- Try a plain rectangle-only SVG.
- Test
imgandobjectseparately. - Verify local-file access or HTTP connectivity.
- Check that width, height and
viewBoxproduce a visible coordinate system.
The SVG shape appears but nested images do not
- Replace the nested image with a known-good PNG.
- Inspect
href/xlink:hrefresolution from the SVG directory. - Check data-URI completeness and media type.
- Run as the deployment user and capture resource errors.
- Try inline SVG, then test the whole page for collateral changes.
It works locally but fails in production
- Compare
wkhtmltopdf --versionoutput and patched-Qt status. - Compare OS, fonts, working directory, environment variables and service account.
- Use absolute paths or an approved
--allowdirectory. - Check container filesystem mounts, network egress, DNS and TLS.
Base64 did not help
That result is consistent with issue #2996. Base64 removes one external file lookup, but does not fix unsupported SVG features, malformed markup, sizing problems, or a failing inclusion route. Reduce the SVG and test each cause independently.
Performance, reliability and cost considerations
Large inline SVGs increase HTML size and parsing work. Rasterizing once and reusing the result can reduce repeated processing, while remote assets add network latency and another point of failure. Caching generated PDFs is useful only when source HTML, assets and rendering options are immutable; otherwise invalidate the cache when any of those inputs change.
For reliable releases, maintain a fixture set containing external, inline and object SVGs; nested data and relative images; filters and custom fonts; and the largest production dimensions. Compare rendered pages by eye or with image-diff tooling, and run the suite whenever the wkhtmltopdf binary, base image, fonts or templates change.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is a clean screenshot or PDF of a web page rather than preserving a wkhtmltopdf pipeline, ScreenshotNeo provides a website screenshot API and MCP server. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; bot checks, blank pages, timeouts, failed loads and cache hits are not billed, with the result identified by X-Page-Verdict and X-Billed headers. Its MCP server includes take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients.
One-call example (see the ScreenshotNeo documentation):
Recommended Free Tools
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}`);Every plan includes the features: full-page and element capture, device presets or custom viewports, retina scale, dark mode, PDF controls, custom CSS and JavaScript, click and wait actions, request/resource blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, chosen-TTL caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage API and OpenAPI specification. Pricing is 1,000 shots per month free with no card; paid plans start at $5 for 3,000 shots, with yearly billing giving two months free.
Create a free ScreenshotNeo account to use the 1,000 monthly shots without a card.
Best Value
- ALL-IN-ONE SOLUTION – read, edit, convert, merge and protect your PDF files
- MAXIMUM FUNCIONALITY – create interactive forms, compare PDFs, bates numbering, find and replace text or colors, convert documents, OCR engine, comment, highlight, fill out and print forms, document protection and others
- EASY TO INSTALL AND USE – well-structured user-interface, in-program instructions, free tech support whenever you need it
- GREAT VALUE FOR MONEY - why spend a fortune if you can have maximum functionality at a reasonable price - this also fits the requirements of companies very well
FAQ
Does wkhtmltopdf support every SVG that Chrome supports?
No. It uses an older Qt WebKit engine, so browser success is not proof of equivalent support.
Should I always convert SVGs to PNG?
No. Rasterization is a practical fallback when a specific graphic remains unreliable, but test resolution and file size at the final PDF dimensions.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Is --enable-local-file-access safe for every deployment?
It broadens local-file access. Prefer an explicit allowed directory where possible, and run the converter with a least-privileged account.
Frequently Asked Questions
Can a relative image path inside an SVG be resolved from the HTML directory?
Usually it is resolved relative to the SVG document’s own location. Verify the resolved path under the same user and filesystem used by wkhtmltopdf.
What should be stored for a reproducible bug report?
Store the exact version output, operating system or container, minimal HTML/SVG files, command line, stderr, exit code and the resulting PDF.
The Bottom Line
Fix SVG embedding failures by isolating the inclusion route, validating nested-resource access and testing the exact wkhtmltopdf build. If the legacy engine still cannot render the required SVG features, rasterize the affected artwork or move to a maintained renderer after testing complete documents.
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.
