If wkhtmltopdf produces a PDF before a JavaScript page is complete, first determine whether you have a timing problem at all. Record the exact wkhtmltopdf --version output, operating system, package source and full command. Then test --javascript-delay and --window-status separately on a tiny page. A longer delay helps only when the page is still executing successfully; it cannot repair a JavaScript exception, blocked request, disabled script or unsupported browser feature.
What the two settings actually do
--javascript-delay is a fixed wait
The command-line documentation describes --javascript-delay <msec> as waiting a specified number of milliseconds after page loading for JavaScript to finish. Its documented default is 200 ms. It is a clock, not an application-level readiness check: wkhtmltopdf does not know whether your API request, chart, framework hydration or animation has completed.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
Image to PDF Converter | Buy on Amazon |
Use it when rendering time is predictably bounded. For example:
wkhtmltopdf --javascript-delay 2000 https://example.com report.pdfIf increasing the value changes the PDF, the page may simply need more time. If the output never changes, stop increasing it and investigate execution and loading.
#1 Best Overall
- All item converter to pdf
--window-status waits for an exact signal
--window-status <value> waits until the page’s window.status equals the supplied string. The page must set that exact value in the rendering context:
<script>
fetch('/data.json')
.then(r => r.json())
.then(data => {
renderReport(data);
window.status = 'ready';
})
.catch(err => {
console.error(err);
window.status = 'failed';
});
</script>Run it with:
wkhtmltopdf --window-status ready report.html report.pdfThe string is case-sensitive. If the assignment never runs, a request never resolves, or an exception occurs first, wkhtmltopdf can wait indefinitely.
Which one wins when both are supplied?
Do not rely on an “either/or” rule across versions. A historical report for 0.12.2.1 observed that using both options appeared to wait for the longer period, and the issue was raised because the interaction was not clearly documented. Test each option alone with your installed build before combining them.
Build a minimal reproduction before changing the application
- Save this file as
delay-test.html:
<!doctype html>
<html><body>
<div id="result">Not ready</div>
<script>
setTimeout(function () {
document.getElementById('result').textContent = 'Ready';
window.status = 'ready';
}, 1000);
</script>
</body></html>- Test the fixed delay by itself:
wkhtmltopdf --javascript-delay 1500 delay-test.html delay.pdf. - Test the readiness signal by itself:
wkhtmltopdf --window-status ready delay-test.html status.pdf. - Open both PDFs and confirm they contain “Ready”.
- Only after this works, reintroduce your framework, external scripts, API calls and CSS.
This isolates wkhtmltopdf behavior from application complexity. Keep the version, operating system and installation method beside the test results; reports involving 0.12.2.1, 0.12.2.4 with patched Qt and 0.12.5 on Windows demonstrate that build differences matter.
Check JavaScript and diagnostic settings
Confirm JavaScript is enabled
JavaScript is enabled by default in the documented CLI options, but a wrapper or command may add --disable-javascript. Remove that switch or explicitly use:
wkhtmltopdf --enable-javascript --javascript-delay 2000 input.html output.pdfIn a C API integration, inspect the corresponding setting rather than assuming CLI spelling maps directly: web.enableJavascript.
Expose errors and slow-script behavior
Use JavaScript diagnostics while debugging:
wkhtmltopdf --debug-javascript --javascript-delay 2000 input.html output.pdfThe option can reveal syntax errors, failed calls and other warnings. The CLI also provides --run-script for an additional script after page load and --no-stop-slow-scripts to alter slow-script handling. These controls do not make unsupported code compatible.
For libwkhtmltox, the related documented settings include load.jsdelay, load.debugJavascript and load.stopSlowScript. Verify the values actually passed by your wrapper.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Choose the correct waiting strategy
| Approach | Best use | Risk |
|---|---|---|
| Fixed delay | Work completes within a known, stable time | Too short gives incomplete output; too long wastes time |
| Window status | Your code controls a reliable completion signal | Missing or mismatched status can wait forever |
| Diagnostics and reproduction | You suspect errors, blocked resources or compatibility | Not a timing strategy; it identifies the real cause |
Use a delay as a diagnostic first. If 500 ms, 2,000 ms and 10,000 ms produce identical incomplete files, timing is probably not the problem. Use window.status only after the page can set it after the exact content needed in the PDF is present.
Common causes and fixes
The page changes only in Chrome
wkhtmltopdf uses an older QtWebKit rendering engine, so code that works in a current browser may fail here. An issue involving plotly.js reported that the expected status-setting path did not run under that setup. Treat this as a compatibility symptom: simplify the page, inspect debug output and test the library in the minimal file rather than assuming every Plotly page fails.
An external script or request is blocked
Check URLs, certificates, authentication, redirects and network access from the machine running wkhtmltopdf. A failed library load means your completion callback may never execute. Inline a small script in the reproduction to distinguish network failure from JavaScript failure.
The status value is never matched
Ensure the command and page use exactly the same value, including capitalization. Set the status only after rendering finishes, not merely after starting an asynchronous request. Add a visible marker beside the status assignment so you can tell whether that branch ran.
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 & 11The process hangs forever
This commonly indicates a readiness condition that never occurs. Run without --window-status and with a finite delay; if that completes, fix the page’s signal or remove the condition. Do not combine an unverified status signal with a long delay and assume one will terminate the other.
JavaScript is stopped as “slow”
Use debug output and test --no-stop-slow-scripts. If the page then renders, reduce expensive work or provide a simpler print path. Disabling the safeguard can increase resource use and does not solve an infinite loop.
Library integrations: map settings explicitly
When calling libwkhtmltox, inspect the object and setting scope. JavaScript enablement belongs to the web settings, while the delay and diagnostics belong to load settings:
web.enableJavascript = true;
load.jsdelay = 2000;
load.debugJavascript = true;
load.stopSlowScript = false;Use the names and types required by your language binding; this illustrative mapping is not a substitute for checking the binding’s API. A frequent failure is setting a CLI-looking name on the wrong object and silently retaining the default.
Free tools Windows power users keep installed
One-click scans. No signup required.
Make failures observable
- Log
wkhtmltopdf --version, OS edition, architecture and installation source. - Save the exact command with secrets removed.
- Record whether delay-only and status-only runs finish.
- Capture JavaScript debug output and exit code.
- Include a small HTML/CSS/JS file that reproduces the issue without proprietary application code.
- Describe expected versus actual PDF content and whether the problem is deterministic.
The project support guidance asks for version details and a detailed reproducible case. A minimal case also makes it possible to identify a build-specific regression instead of endlessly adjusting milliseconds.
Performance, reliability and security considerations
Every extra fixed millisecond increases batch time, even when the page finished earlier. A readiness signal can reduce wasted waiting, but only if it is guaranteed to run on success and failure paths. Add an application-level timeout to your job runner so a hung conversion cannot consume a worker indefinitely.
Keep generated HTML and assets deterministic where possible: pin script versions, avoid animations, wait for fonts and images explicitly, and ensure API calls have bounded timeouts. Do not process untrusted HTML casually. The project status guidance warns about this operational risk; isolate conversion workers and restrict network access when documents are not trusted.
Or skip the browser setup
If your goal is simply a reliable image or PDF of a JavaScript-rendered page, 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; each step can be disabled. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing result.
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 →One GET request returns PNG, JPEG, WebP or PDF. See the ScreenshotNeo documentation for all options, including waits for selectors, delays or network idle, full-page lazy-image loading, custom JavaScript, headers and cookies, PDF page ranges and asynchronous jobs.
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}`);An MCP server supplies take_screenshot, get_page_info and capture_pdf tools to Claude, Cursor and other MCP clients. The Free plan includes 1,000 screenshots monthly without a card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Frequently Asked Questions
Can I set both options as a fallback?
Test them independently first. Their interaction is not a documented cross-version contract, and one historical build appeared to wait for the longer period.
Why does a longer delay never fix the PDF?
A delay cannot repair JavaScript exceptions, blocked resources, disabled scripts or browser-engine incompatibility.
What should I include in a bug report?
Provide the exact version and OS, sanitized command, minimal reproduction, debug output, expected result and separate delay-only and status-only results.
The Bottom Line
Treat --javascript-delay as a bounded pause and --window-status as an exact application signal. Isolate the behavior, verify JavaScript execution and resources, then address build compatibility before adding more milliseconds.
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.
