Start by removing -q (or --quiet) from your command. In wkhtmltopdf 0.12.6 with patched Qt, the documented default log level is already info. Quiet mode changes it to none, hiding the messages that explain failed loads, JavaScript problems, and missing assets. Re-run the smallest failing conversion at the normal information level, record the exact version and operating system, then add JavaScript or loading-specific options only when the evidence points there.
The fastest diagnostic command
Use a command like this while investigating a failure:
wkhtmltopdf --log-level info input.html output.pdf--log-level accepts none, error, warn, and info. The manual lists info as the default, so specifying it makes your intent explicit without pretending that wkhtmltopdf has a documented debug level. The compatibility switches -q and --quiet are equivalent to --log-level none; do not use them during diagnosis.
Preserve the complete command and all output. In a POSIX shell, capture standard output and standard error together:
Recommended Free Tools
#1 Best Overall
- Convert your PDF files into Word, Excel & Co. the easy way
- Convert scanned documents thanks to our new 2022 OCR technology
- Adjustable conversion settings
- No subscription! Lifetime license!
- Compatible with Windows 11, 10, 8.1, 7 - Internet connection required
wkhtmltopdf --log-level info input.html output.pdf >wkhtmltopdf.log 2>&1On Windows PowerShell, a transcript or redirection can serve the same purpose:
wkhtmltopdf --log-level info input.html output.pdf *> wkhtmltopdf.logThese commands retain evidence; they do not fix a resource or rendering problem by themselves.
Record the build before changing options
Run the version command and record your operating-system name and version before experimenting:
wkhtmltopdf --versionThe manual discussed here is generated for wkhtmltopdf 0.12.6 with patched Qt. The project’s downloads page describes 0.12.6 as the stable series and dates that release to June 11, 2020. A distribution package may differ in build, patches, or available switches, so never assume that another machine exposes identical behavior. The project’s support instructions ask for the executable version, operating system and version, a detailed description, and a test case that duplicates the issue when reporting a defect: https://wkhtmltopdf.org/support.html.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesChoose the diagnostic switch that matches the question
| Question | Documented option | What it changes |
|---|---|---|
| Why did the conversion warn or fail? | --log-level info (or a narrower warn/error) |
Controls general diagnostic output. The documented levels are none, error, warn, and info. |
| Did page scripts fail or run unexpectedly? | --debug-javascript |
Enables JavaScript debugging output; it is separate from general log verbosity. |
| Is the main document or a subresource failing? | --load-error-handling |
Chooses abort, ignore, or skip for page-load errors; the documented default is abort. |
| Is a stylesheet, image, or other media failing? | --load-media-error-handling |
Uses its own abort, ignore, or skip policy; the documented default is ignore. |
| Can local HTML read local assets? | --allow <path>, --enable-local-file-access, --disable-local-file-access |
Controls local-file access. --allow can be repeated for narrowly scoped paths. |
Changing an error policy only changes whether conversion aborts, skips a resource, or continues. It does not repair the URL, file, permission, certificate, or script that caused the error. Keep a run with the original defaults so you do not lose the first failure evidence.
Rank #2
![Doxillion Free Document Converter – Converts DOCX, DOC, PDF, WPS and Many More Files Quickly [Download]](https://m.media-amazon.com/images/I/81tjL48MwxL.png._SL160_.png)
- Convert over 50 document file formats.
- Preview your files from Doxillion before converting them.
- Use batch conversion to convert thousands of files at once.
- Enjoy an easy-to-use, intuitive interface with a Drag and Drop file option.
- Burn your converted or original files directly to disc.
Debug JavaScript separately from normal logging
If the HTML depends on script execution, combine the normal log level with the dedicated JavaScript switch:
wkhtmltopdf --log-level info --debug-javascript input.html output.pdfFor pages that render after an asynchronous operation, two timing controls are relevant:
--javascript-delay <msec>waits after page loading; the documented default is 200 milliseconds.--window-status <windowStatus>waits until the page’swindow.statusmatches the supplied value.
For example:
wkhtmltopdf --log-level info --debug-javascript --javascript-delay 1500 input.html output.pdfA longer delay can expose late-rendered content, but it cannot make a browser-incompatible application work. Prefer --window-status when your page can deliberately set a completion marker, because it expresses a condition rather than an arbitrary wait.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Interpret incomplete output without guessing
Main-page failures
When the document itself cannot be fetched or parsed, inspect the messages from the normal log first. Re-run with the default --load-error-handling abort so the failure remains visible. Only after identifying the failing request should you test ignore or skip to determine whether the rest of the document is usable.
Media-resource failures
Images, stylesheets, fonts, and other media follow the separate --load-media-error-handling policy, whose documented default is ignore. A PDF can therefore be produced while silently lacking a visual asset. Temporarily choose abort when you need the conversion to stop at a missing media resource, then fix the URL, server response, or file path rather than leaving the relaxed policy as a supposed solution.
Rank #3
- 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
- 1 Year License for 1 Windows & 2 Mobile (Android and/or iOS) devices.
Local-file access
For an input such as file:///work/report/index.html that references files in /work/report/assets, grant only the directory required:
wkhtmltopdf --log-level info --allow /work/report/assets /work/report/index.html report.pdfThe manual also documents --enable-local-file-access and --disable-local-file-access. Use the narrowest setting compatible with your job. A missing stylesheet or image can look like a CSS problem when it is actually an access restriction.
Build a reproducible test case
- Save the exact
wkhtmltopdf --versionresult and operating-system/version details. - Copy the complete command, including every option, input URL or file path, and output path.
- Replace the production page with a minimal HTML file that still demonstrates the symptom. Keep one suspect script, URL, or local asset at a time.
- Run that same input with the same installed build and
--log-level info; add--debug-javascriptonly if scripts are implicated. - Compare a baseline run with the run that changes one loading or access option. Record whether the PDF aborts, completes, or omits content.
- For a project report, include the requested detailed description and a test case that duplicates the issue.
This method prevents a changed timeout, error policy, package build, and input from being conflated. The available documentation does not define universal warning-to-root-cause mappings or exit-code meanings for every build, so treat each message as a lead to verify against the reduced case.
Troubleshooting branches
The log is empty
- Remove
-qand--quiet; both select--log-level none. - Ensure your wrapper is not discarding standard error before it reaches your terminal or log file.
- Run the executable directly and capture both streams as shown above.
The PDF exists but content is missing
- Re-run with
--log-level infoand temporarily set media handling toabortto expose a missing asset. - Check every relative URL, redirect, certificate, and local-file permission in the reduced HTML.
- If content is script-generated, add
--debug-javascriptand use a deliberate--window-statusmarker or an appropriate delay.
Local images or CSS do not load
- Verify the paths from the HTML file’s location, not from your shell’s current directory.
- Use a narrowly scoped repeatable
--allow <path>, or confirm whether your build requires the documented local-access switch. - Do not enable broad access merely to hide an incorrect path.
A relaxed error policy appears to “fix” the job
ignore and skip can produce a file while omitting the failed material. Keep the aborting baseline, identify the resource, and correct it before adopting a less strict policy for a deliberate fallback.
Different machines produce different results
Compare the executable version, patched-Qt build, operating system, fonts, input URL/file, and complete command. The 0.12.6 manual is not proof that a vendor package has the same feature set.
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
Security and reliability boundaries
wkhtmltopdf runs headlessly, but it is not a safe sandbox for arbitrary user content. The project warns: “Do not use wkhtmltopdf with any untrusted HTML – be sure to sanitize any user-supplied HTML/JS, otherwise it can lead to complete takeover of the server it is running on!” Treat HTML, JavaScript, URLs, cookies, and local-file permissions as untrusted inputs unless your application has validated them. Run conversions with least-privilege accounts, isolate sensitive files, and avoid broad local access.
For reliable diagnostics, keep a known-good fixture, pin the executable build where practical, save logs with the generated PDF, and change one variable per run. Verbose output is evidence collection, not a guarantee that a modern web application will render correctly.
Or skip the browser setup
If your goal is simply a clean image or PDF of a web page rather than debugging a local wkhtmltopdf conversion, ScreenshotNeo provides a one-call website screenshot API and MCP server. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; the response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers.
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 complete option list and response details in the ScreenshotNeo documentation. The service includes an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. One thousand screenshots per month are free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
FAQ
Does wkhtmltopdf have a documented debug log level?
No. The documented levels are none, error, warn, and info. JavaScript diagnostics use the separate --debug-javascript switch.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Should I leave --load-error-handling ignore enabled in production?
Only if omitted resources are an intentional, monitored fallback. Otherwise retain the stricter baseline and fix the failing resource.
Best Value
![Doxillion Free Document Converter for Mac – Converts DOCX, DOC, PDF, WPS and Many More Files Quickly [Download]](https://m.media-amazon.com/images/I/51Xjwhv3w2L._SL160_.jpg)
- Convert over 50 document file formats.
- Preview your files from Doxillion before converting them.
- Use batch conversion to convert thousands of files at once.
- Enjoy an easy-to-use, intuitive interface with a Drag and Drop file option.
- Burn your converted or original files directly to disc.
What should accompany a bug report?
Provide the executable version, operating-system/version, detailed issue description, complete command, captured output, and a minimal test case that reproduces the behavior.
Frequently Asked Questions
Does wkhtmltopdf have a documented debug log level?
No. The documented levels are none, error, warn, and info. JavaScript diagnostics use the separate –debug-javascript switch.
Should I leave –load-error-handling ignore enabled in production?
Only if omitted resources are an intentional, monitored fallback. Otherwise retain the stricter baseline and fix the failing resource.
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 minuteWhat should accompany a bug report?
Provide the executable version, operating-system/version, detailed issue description, complete command, captured output, and a minimal test case that reproduces the behavior.
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.
