Most wkhtmltopdf failures fall into one of four stages: the executable cannot run, the page or an asset cannot load, JavaScript has not finished creating the chart, or Chart.js receives the wrong container size. Capture the complete command and unabridged output first, then isolate the failing stage. A reliable fix usually combines a verified binary and permissions check, explicit JavaScript diagnostics and delay, and a Chart.js container with dimensions that match the PDF layout.
Start with evidence, not guesses
Save the exact command, working directory, input HTML, output path, standard output, and standard error. Also record the account running the command, executable path, operating-system version, and wkhtmltopdf --version. A numeric exit code is only a symptom; the text around it identifies the phase that failed.
Make a minimal HTML/CSS/JavaScript reproduction containing one chart and the same asset-loading method as production. The wkhtmltopdf project asks issue reports to include the version, OS and version, a detailed description, and a reproducible HTML/CSS/JS case (official reporting guidance).
Fix executable and permission failures
Confirm the binary selected by your wrapper
- Find the path used by your application (for example, with
command -v wkhtmltopdfon Unix-like systems). - Run that exact path directly:
/path/to/wkhtmltopdf --version. - Check that the file exists, is executable, and is readable by the service account. On Unix,
ls -l /path/to/wkhtmltopdfandnamei -l /path/to/wkhtmltopdfexpose directory and file permissions. - Run the command as the same user as the web worker, queue, container, or scheduled job—not only as an administrator.
Exit status 126 can appear with a shell message such as “Permission denied.” Issue #4283 is a concrete example, not a universal definition of every 126 result (issue #4283). Correct the selected path, execute bit, mount policy, or service-account permissions, then rerun the minimal command.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →#1 Best Overall
- INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
- COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
- ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
- HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs
Check the actual wkhtmltopdf generation
The project downloads page lists 0.12.6 as its stable series, released June 11, 2020 (downloads page). That date does not establish compatibility with every current JavaScript or CSS feature. Reproduce on the binary and OS you will deploy; do not silently substitute a different build.
Separate page loading from chart rendering
Verify JavaScript and diagnostics
JavaScript is enabled by default in the command-line manual, but wrappers can add conflicting switches. Start with explicit settings and diagnostic output:
wkhtmltopdf
--enable-javascript
--debug-javascript
--javascript-delay 1000
input.html output.pdfThe documented default delay is 200 milliseconds. It is a default, not proof that an asynchronous Chart.js application has finished. Increase it only after observing logs and validating the resulting PDF; there is no universal wait value. To prove that JavaScript is the problem, temporarily run the same input with --disable-javascript and compare the failure mode (command-line usage manual).
Confirm every resource URL
Open the minimal file in the same environment and verify that the Chart.js script, data, fonts, and stylesheets load. A browser tab on your laptop can succeed while a server-side process cannot resolve a private hostname, certificate, authentication header, or relative path. Use absolute, reachable URLs or package assets with the HTML. Check the manual’s load-error and local-file-access options, then inspect the help output of your installed build because behavior and available switches can differ.
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 minuteIf you rely on a local script, test an explicit local-file policy rather than changing it blindly. Keep the change narrow, and never expose untrusted HTML or JavaScript to the renderer. The wkhtmltopdf 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!” (project downloads page).
Give Chart.js a PDF-sized responsive container
Chart.js responsiveness is based on the parent container, not on the canvas alone. The documented pattern uses a dedicated parent with position: relative; that parent should contain only the chart canvas (Chart.js responsive charts).
Rank #2
- CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
- INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
- PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
- ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<style>
.chart-container {
position: relative;
width: 680px;
height: 320px;
}
</style>
</head>
<body>
<div class="chart-container">
<canvas id="sales-chart"></canvas>
</div>
<script>
const canvas = document.getElementById('sales-chart');
new Chart(canvas, {
type: 'line',
data: {
labels: ['Jan', 'Feb', 'Mar', 'Apr'],
datasets: [{
label: 'Sales',
data: [12, 19, 14, 23],
borderColor: '#2563eb',
backgroundColor: 'rgba(37,99,235,.15)',
fill: true,
tension: .25
}]
},
options: {
responsive: true,
maintainAspectRatio: false,
animation: false
}
});
</script>
</body>
</html>maintainAspectRatio is true by default. Set it to false when the parent’s explicit height must control the chart. The default aspect ratio is 2 for most chart types and 1 for radial types. If height is explicitly supplied through an attribute or style, Chart.js ignores the aspectRatio option. Give each chart its own sized container instead of putting several canvases in one responsive wrapper.
Account for print layout changes
Print CSS, page breaks, and PDF margins can change the container after the chart was created. Chart.js documents resizing to explicit dimensions before printing and calling resize without arguments afterward:
window.addEventListener('beforeprint', () => {
chart.resize(680, 320);
});
window.addEventListener('afterprint', () => {
chart.resize();
});For wkhtmltopdf, a deterministic fixed container often works better than waiting for a browser window to settle. If your page changes classes or dimensions asynchronously, perform that work before constructing the chart, or increase --javascript-delay and confirm the output visually.
Use a controlled command while debugging
Once the minimal page works, add production options one at a time. This baseline writes diagnostics to the terminal and produces a PDF:
wkhtmltopdf
--enable-javascript
--debug-javascript
--javascript-delay 1500
--page-size A4
--print-media-type
chart.html chart.pdfDo not assume --print-media-type or a longer delay fixes a missing chart. They change rendering conditions; they do not repair a missing script, blocked request, or zero-height parent. Keep a known-good command beside the production wrapper so regressions can be bisected.
Read the symptom and choose the matching fix
| Symptom | Likely phase | Evidence to collect | Targeted action |
|---|---|---|---|
| Status 126, permission-denied text | Executable | Resolved path, file and directory permissions, calling user | Run the selected binary as that user; repair execute permission or path |
| Immediate nonzero exit with missing-resource text | Page or asset loading | stderr, URLs, certificates, local-file policy | Make resources reachable; review load-error and local-file options |
| Successful PDF with blank canvas | JavaScript completion | Debug output, script response, chart-construction timing | Enable JavaScript, verify Chart.js loads, wait only as long as required |
| Chart clipped, tiny, or stretched | Layout | Parent width/height at render time, print CSS | Use a relative dedicated container and set maintainAspectRatio: false when appropriate |
| Chart differs only in PDF | Print layout | Before/after dimensions and page-break rules | Resize explicitly around print rendering and validate the target binary |
Common errors and recovery steps
“Command not found” or a wrapper cannot start
Log the absolute executable path instead of relying on the service account’s PATH. Install or reference the intended build, then rerun --version under the worker account. A wrapper may point to a removed package even though an interactive shell has another binary.
Recommended Free Tools
Rank #3
- SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
- INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
- KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
- PREMIUM SUPPORT - Strong technical expertise to solve issues faster
- THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.
Exit status 1 with no visible chart
Preserve stderr; do not discard it in the wrapper. Test a static HTML file first, then add the Chart.js script, then data fetching. This identifies whether the failure is the renderer, a resource, or application JavaScript.
Pie or doughnut chart is incomplete
Reduce the page to one chart and fixed data, enable debug output, and test the exact binary. Issue #4923 demonstrates an incomplete pie-chart report but does not establish a universal cause (issue #4923).
Local files work interactively but not in production
Compare the user, current directory, URL form, and local-file policy. Prefer a controlled asset directory and explicit paths. Avoid broad permissions or accepting arbitrary file URLs.
Changing the delay never helps
A delay cannot load a script that failed, fix a zero-height container, or bypass a blocked request. Inspect debug output and network reachability first; then set the smallest delay that consistently captures a completed chart.
Reliability, performance, and security checklist
- Pin and document the wkhtmltopdf binary, OS image, fonts, and wrapper version.
- Render a minimal fixture in CI and compare that PDF whenever the HTML or renderer changes.
- Keep charts deterministic: supply data in the page when possible, disable unnecessary animation, and avoid indefinite polling.
- Set explicit container dimensions for the target paper size and test page breaks with realistic labels.
- Capture full logs, output size, and render duration so timeouts are distinguishable from blank charts.
- Sanitize all user-supplied HTML and JavaScript. The project’s security warning applies even when the command appears to be an internal utility.
Or skip the browser setup
If you need a clean image or PDF rather than a locally managed wkhtmltopdf runtime, ScreenshotNeo provides a 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; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result.
One GET request is enough:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for options such as full-page lazy-image capture, CSS-selector element shots, device and retina settings, PDF paper and margin controls, custom CSS/JavaScript, waits, request blocking, headers, cookies, geolocation, caching, signed links, asynchronous webhooks, bulk capture, and usage reporting. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
Rank #4
- Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
- No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
- Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
- Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
- The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
When to report a wkhtmltopdf bug
Report only after reproducing with the real binary, OS, account, inputs, assets, and wrapper. Include the exact version, operating-system version, complete command, unabridged output, and a small HTML/CSS/JavaScript case. That information lets maintainers distinguish an execution failure from a resource, JavaScript, or layout problem.
Frequently Asked Questions
What does wkhtmltopdf exit code 126 mean?
It can accompany a shell permission-denied message, as shown by issue #4283. Verify the exact executable path and permissions for the account running the command; do not treat 126 as a complete diagnosis.
What delay should I use for Chart.js?
The documented default is 200 milliseconds, but asynchronous pages need different waits. Use debug output and visual or automated PDF validation, then choose the smallest page-specific delay that consistently captures the completed chart.
Why is my responsive chart the wrong height?
Chart.js sizes responsively from its parent. Give the canvas a dedicated relatively positioned parent with an explicit height and set maintainAspectRatio: false when that parent-controlled height is required.
Which wkhtmltopdf version is current?
The project downloads page lists 0.12.6 as the stable series, released June 11, 2020. Test that—or your deployed build—on the exact operating system and assets you use.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
