Start with diagnostics and an explicit wait:
wkhtmltopdf --debug-javascript --javascript-delay 1000 input.html output.pdf
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 problemsThis command enables JavaScript debugging output and waits one second before rendering. Confirm that your command does not contain --disable-javascript. If the page can signal when its dynamic content is complete, a window.status marker with --window-status is usually more reliable than guessing a delay. Then check resource access, the exact wkhtmltopdf/Qt build, and whether the page uses browser APIs that this renderer supports.
What wkhtmltopdf is doing when JavaScript fails
wkhtmltopdf loads HTML in its embedded Qt-based browser, executes page scripts when JavaScript is enabled, and then renders the document. A PDF can therefore be wrong for several different reasons:
- JavaScript was disabled by the command, wrapper, or library settings.
- The script threw an error or used an API unavailable in the installed build.
- Asynchronous data had not arrived before rendering began.
- A local script, stylesheet, font, image, or data file was blocked.
- The binary or Qt integration differs from the environment where the page worked.
Treat “the PDF is missing dynamic content” as a diagnosis to separate, not as proof that JavaScript is unsupported.
1. Record the exact executable and invocation
Before changing flags, capture the version and the complete command:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
wkhtmltopdf --version wkhtmltopdf --debug-javascript --javascript-delay 1000 input.html output.pdf
Also record whether the source is a local file or URL, and whether a wrapper, application library, container, or operating-system package launches wkhtmltopdf. Different builds expose different Qt features, so a result from one installation cannot automatically be generalized to another.
2. Turn on JavaScript diagnostics
The CLI option --debug-javascript means “Show javascript debugging output” in the project documentation. Use it while reproducing the problem and preserve the process output from your shell, service log, or wrapper. The exact messages depend on the binary and how it is invoked. If your wrapper hides stderr, configure it to forward that stream.
For the library interface, the corresponding settings are web.enableJavascript and load.debugJavascript. A library can also expose JavaScript warnings and errors through its callback mechanism; verify that your application actually records those callbacks.
3. Verify that JavaScript is enabled
The documented CLI default is JavaScript enabled. An explicit --disable-javascript overrides that default:
wkhtmltopdf --disable-javascript input.html output.pdf
Remove that option, or use --enable-javascript explicitly while testing:
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
wkhtmltopdf --enable-javascript --debug-javascript input.html output.pdf
In a library integration, inspect web.enableJavascript. A command-line test may work while an application test fails if the wrapper sets this property differently.
4. Separate timing problems from execution problems
Use a controlled fixed delay
--javascript-delay <msec> waits after page loading before rendering. The documented default is 200 milliseconds, which is often shorter than an API request, chart animation, or client-side framework startup.
wkhtmltopdf --debug-javascript --javascript-delay 3000 https://example.com report.pdf
Increase the value temporarily to determine whether timing is involved. A fixed delay is only a heuristic: a slow request can still finish late, while a fast page makes a large delay waste conversion time.
Use a page-controlled readiness marker
If you control the page, set window.status only after the required content has rendered:
<script>
fetch('/report-data.json')
.then(response => response.json())
.then(data => {
renderReport(data);
window.status = 'ready';
})
.catch(error => {
console.error(error);
window.status = 'failed';
});
</script>
Then wait for the marker:
wkhtmltopdf --debug-javascript --window-status ready report.html report.pdf
This expresses actual completion instead of assuming that a particular number of milliseconds is sufficient. If the assignment is never reached, wkhtmltopdf can continue waiting; enforce a bounded timeout in the calling service and emit a useful failure. Make sure every branch that should produce a PDF reaches the intended status value.
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
Do not assume combined-option precedence
The CLI documents both --javascript-delay and --window-status, but it does not define every interaction between them. A 2015 issue report for wkhtmltopdf 0.12.2.1 described an observation that using both appeared to wait for the longer interval. That is a version-specific user report, not a rule for every build. Test your installed binary with a page that sets status after a known interval, and avoid relying on undocumented precedence.
5. Use the relevant JavaScript controls
| Option or setting | Purpose | Important limitation |
|---|---|---|
--debug-javascript |
Shows JavaScript debugging output. | Exact output depends on the binary and invocation. |
--enable-javascript / --disable-javascript |
Allows or blocks page scripts. | JavaScript is enabled by default in the documented CLI, but wrappers can override it. |
--javascript-delay <msec> |
Waits a fixed interval before rendering. | The documented default is 200 ms; it cannot know when your request or chart is complete. |
--window-status <value> |
Waits for window.status to equal a value. |
The page must actually assign that value. |
--run-script <js> |
Runs additional JavaScript after page loading. | It cannot add unsupported browser APIs or repair a page that already failed. |
--stop-slow-scripts / --no-stop-slow-scripts |
Controls whether slow-running scripts are stopped. | Disabling stopping can increase hangs and resource use; use it only as a targeted test. |
web.enableJavascript |
Library equivalent of enabling JavaScript. | Inspect the effective library configuration, not just source defaults. |
load.jsdelay |
Library delay setting. | The documentation says it waits for the delay or until JavaScript calls window.print(). |
6. Check local files and deferred resources
A local HTML file may reference scripts, CSS, fonts, images, or JSON in other locations. If those resources are blocked, the page can appear to execute while remaining empty. The CLI provides local-file access controls; use narrow --allow permissions for the directories the document needs instead of broadly enabling access.
Free tools Windows power users keep installed
One-click scans. No signup required.
wkhtmltopdf --debug-javascript --allow /srv/report-assets report.html report.pdf
Confirm that paths are correct from the renderer’s point of view, that permissions allow the wkhtmltopdf process to read them, and that relative URLs resolve against the expected base URL. A minimal document with one script and one data file can reveal whether the problem is access or application logic.
7. Reduce the page to a reproducible case
- Create a small HTML file that writes a visible marker such as
JavaScript ran. - Run it with
--debug-javascriptand a short delay. - Add the asynchronous request, chart, framework bundle, or local resource one at a time.
- Compare the PDF with a modern browser only as a reproduction aid. Different runtimes do not support identical APIs.
- Keep the minimal HTML, command, version, and output when reporting the issue.
This process distinguishes a syntax or timing error from a renderer compatibility issue without attributing every failure to a particular JavaScript library.
Why a modern-browser page can still fail
wkhtmltopdf behavior depends on its build and Qt integration. The project’s downloads and project information page notes that some features require patched Qt and that distributions differ. If a page works in a current browser but not in wkhtmltopdf, check the browser APIs and syntax it uses, record wkhtmltopdf --version, and produce a small reproduction.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
A historical Plotly issue illustrates one user’s failure; it does not establish that every Plotly page, or every current build, is incompatible. Likewise, issue reports are troubleshooting clues rather than universal support statements.
Common symptoms and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Static HTML appears, dynamic section is empty | Rendering began before asynchronous code completed. | Try --javascript-delay as a test, then implement window.status readiness. |
| No JavaScript messages are visible | Debug output is disabled or stderr is hidden by a wrapper. | Add --debug-javascript and capture the process’s stderr/log callback. |
| Scripts never run | --disable-javascript or a library setting disabled them. |
Remove the disable flag and verify web.enableJavascript. |
Renderer waits indefinitely with --window-status |
The page never assigns the requested status, or an earlier exception stops execution. | Log before the assignment, inspect diagnostics, handle error branches, and impose a caller-side timeout. |
| Local assets are missing | File access is blocked or paths resolve incorrectly. | Check absolute/relative paths and grant a narrow --allow directory. |
| Works on one machine only | Different wkhtmltopdf or Qt builds. | Compare versions and package sources, then reproduce with the same binary. |
| Conversion hangs or consumes excessive resources | A slow script, infinite loop, or disabled slow-script stopping. | Re-enable --stop-slow-scripts, simplify the page, and set an external process timeout. |
| Modern syntax or API fails | The embedded runtime lacks that feature. | Transpile or simplify the page for the target runtime, or use a renderer with the required browser support. |
Performance and reliability choices
When to choose a fixed delay
Use a delay when you cannot change the page and need a quick diagnostic or a predictable upper bound. Measure typical completion time in your environment, leave margin for slow responses, and keep the value as small as reliability permits.
When to choose window.status
Use a readiness marker when you own the page or can inject a controlled script. It reduces early renders caused by variable network or data-processing time, but only if every success path reaches the marker and the caller has a timeout.
Control external dependencies
For repeatable jobs, make data requests deterministic, avoid indefinitely retrying client code, and ensure fonts and assets are available to the renderer. Cache or prefetch data in the calling application when that is safer than waiting on a page script.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Library configuration checklist
When using libwkhtmltox instead of the CLI, map the same questions to settings:
Recommended Free Tools
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
- Is
web.enableJavascripttrue? - Is
load.debugJavascriptenabled and its warning/error callback connected? - Is
load.jsdelaylong enough for the test? - Does the library process expose the same local-file access policy as your command-line test?
- Does the linked binary use the same Qt build?
The project’s libwkhtmltox settings reference describes these controls.
Security when converting untrusted HTML
The project’s downloads and project information page warns against using wkhtmltopdf with untrusted HTML without sanitizing user-supplied HTML and JavaScript. A conversion service should isolate the renderer, restrict network and file access, sanitize input, and apply process time and resource limits. Debugging flags do not make untrusted content safe.
Or skip the browser setup
If you need a clean screenshot or PDF rather than a locally managed wkhtmltopdf runtime, ScreenshotNeo provides a website screenshot API and MCP server. Its capture pipeline accepts cookie and consent banners before removing more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be switched off. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing result.
One GET request returns PNG, JPEG, WebP, or PDF. The API supports full-page captures with lazy images loaded, CSS-selector element captures, custom JavaScript and CSS, waits for selectors, delays or network idle, custom headers and cookies, device and viewport settings, PDF paper and margin controls, blocking rules, caching TTLs, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, and usage reporting. AI agents can use its MCP tools take_screenshot, get_page_info, and capture_pdf from Claude, Cursor, or another MCP client.
cURL (see the ScreenshotNeo API documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
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 shots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing provides two months free. Create a free ScreenshotNeo account to start.
References
- wkhtmltopdf CLI usage documentation
- Debian Bookworm wkhtmltopdf man page
- Issue 2616: delay versus window-status report
- Issue 2217: window-status report
- Issue 2721: Plotly JavaScript report
Frequently Asked Questions
What is wkhtmltopdf’s default JavaScript delay?
The documented CLI default is 200 milliseconds. It is a fixed software default, not a guarantee that asynchronous content will be ready.
Can –run-script make unsupported browser APIs work?
No. It can execute additional JavaScript after loading, but it cannot add APIs missing from the embedded runtime.
What should I do if window.status never becomes ready?
Check JavaScript diagnostics and the code path that assigns the status, then add a caller-side timeout so a failed page cannot wait forever.
Crashes, 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 minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Quick 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.
