Start by checking the URL from the same environment that runs wkhtmltopdf, then set Frappe’s host_name to an address that environment can actually resolve and reach. A local Frappe report was fixed with http://127.0.0.1:8000; other deployments may need a host IP, an internal container name, or a public domain and port. Those are reported workarounds, not a universal explanation for every TLS failure.
Do not begin by disabling certificate verification. First identify the failing resource, test DNS and HTTP connectivity from the renderer’s network namespace, correct the generated URL, and then verify the PDF’s layout separately.
What SslHandshakeFailedError means
wkhtmltopdf retrieves the HTML page and its referenced resources—stylesheets, images, fonts, scripts and sometimes API responses—before writing the PDF. The message Exit with code 1 due to network error: SslHandshakeFailedError means a network retrieval failed during that process. It does not, by itself, prove that the website’s certificate is invalid or that one particular TLS setting is wrong.
The browser on your workstation and the application server may both open the page while the wkhtmltopdf process cannot. The renderer might be running in a worker, a separate container, a VM, or a production host with different DNS, routes, firewall rules and proxy settings. Troubleshoot that execution path, not the path from your laptop.
#1 Best Overall
- DUAL-BAND WIFI 6 ROUTER: Wi-Fi 6(802.11ax) technology achieves faster speeds, greater capacity and reduced network congestion compared to the previous gen. All WiFi routers require a separate modem. Dual-Band WiFi routers do not support the 6 GHz band.
- AX1800: Enjoy smoother and more stable streaming, gaming, downloading with 1.8 Gbps total bandwidth (up to 1200 Mbps on 5 GHz and up to 574 Mbps on 2.4 GHz). Performance varies by conditions, distance to devices, and obstacles such as walls.
- CONNECT MORE DEVICES: Wi-Fi 6 technology communicates more data to more devices simultaneously using revolutionary OFDMA technology
- EXTENSIVE COVERAGE: Achieve the strong, reliable WiFi coverage with Archer AX1800 as it focuses signal strength to your devices far away using Beamforming technology, 4 high-gain antennas and an advanced front-end module (FEM) chipset
- OUR CYBERSECURITY COMMITMENT: TP-Link is a signatory of the U.S. Cybersecurity and Infrastructure Security Agency’s (CISA) Secure-by-Design pledge. This device is designed, built, and maintained, with advanced security as a core requirement.
1. Capture the complete failure
Save the renderer’s standard error and record the exact URL passed to it. If you can reproduce the problem from a shell, redirect stderr:
wkhtmltopdf https://example.test/invoice/42 invoice.pdf 2> wkhtmltopdf.stderrIn an application, collect the full PDF-generation traceback and wkhtmltopdf output rather than only the final “exit code 1” line. Note whether the failing page is an internal Frappe route, a public HTTPS URL, or a resource referenced by the page. A stylesheet or image can fail even when the top-level document loads.
Also record the renderer version:
wkhtmltopdf --versionThe available evidence is from community support reports, not a compatibility matrix for every wkhtmltopdf or Frappe release. Keeping the version in the incident record prevents a configuration fix from being mistaken for a version guarantee.
2. Test connectivity where wkhtmltopdf runs
Find the execution environment
Run the checks in the same worker, container, VM or host that launches wkhtmltopdf. If a background job creates PDFs, running curl on your desktop is not an equivalent test. For a container deployment, open a shell in the PDF-generating container; for a managed process, use its host or an approved diagnostic job.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Check DNS
Resolve the hostname used by the generated page:
getent hosts erp.example.comIf this returns no address, fix the container’s DNS or use a hostname resolvable on that network. An address that resolves on the web server may not resolve in the worker’s network namespace.
Check the route and HTTP response
Request the same URL with a short timeout:
curl -I --max-time 20 https://erp.example.com/invoice/42Use the same scheme, port and hostname that appear in the HTML. A successful response from curl proves only that this particular request worked; assets can still point at a different host, an inaccessible port, or a URL requiring authentication that wkhtmltopdf does not have.
If the page is protected, reproduce the relevant headers or cookies in a controlled diagnostic request. Do not paste credentials into logs. A DNS answer, a TCP connection, and a usable HTTP response are separate checks; failure at any one of them can surface as a renderer network error.
Rank #2
- 𝐅𝐮𝐭𝐮𝐫𝐞-𝐑𝐞𝐚𝐝𝐲 𝐖𝐢-𝐅𝐢 𝟕 - Designed with the latest Wi-Fi 7 technology, featuring Multi-Link Operation (MLO), Multi-RUs, and 4K-QAM. Achieve optimized performance on latest WiFi 7 laptops and devices, like the iPhone 16 Pro, and Samsung Galaxy S24 Ultra.
- 𝟔-𝐒𝐭𝐫𝐞𝐚𝐦, 𝐃𝐮𝐚𝐥-𝐁𝐚𝐧𝐝 𝐖𝐢-𝐅𝐢 𝐰𝐢𝐭𝐡 𝟔.𝟓 𝐆𝐛𝐩𝐬 𝐓𝐨𝐭𝐚𝐥 𝐁𝐚𝐧𝐝𝐰𝐢𝐝𝐭𝐡 - Achieve full speeds of up to 5764 Mbps on the 5GHz band and 688 Mbps on the 2.4 GHz band with 6 streams. Enjoy seamless 4K/8K streaming, AR/VR gaming, and incredibly fast downloads/uploads.
- 𝐖𝐢𝐝𝐞 𝐂𝐨𝐯𝐞𝐫𝐚𝐠𝐞 𝐰𝐢𝐭𝐡 𝐒𝐭𝐫𝐨𝐧𝐠 𝐂𝐨𝐧𝐧𝐞𝐜𝐭𝐢𝐨𝐧 - Get up to 2,400 sq. ft. max coverage for up to 90 devices at a time. 6x high performance antennas and Beamforming technology, ensures reliable connections for remote workers, gamers, students, and more.
- 𝐔𝐥𝐭𝐫𝐚-𝐅𝐚𝐬𝐭 𝟐.𝟓 𝐆𝐛𝐩𝐬 𝐖𝐢𝐫𝐞𝐝 𝐏𝐞𝐫𝐟𝐨𝐫𝐦𝐚𝐧𝐜𝐞 - 1x 2.5 Gbps WAN/LAN port, 1x 2.5 Gbps LAN port and 3x 1 Gbps LAN ports offer high-speed data transmissions.³ Integrate with a multi-gig modem for gigplus internet.
- 𝐎𝐮𝐫 𝐂𝐲𝐛𝐞𝐫𝐬𝐞𝐜𝐮𝐫𝐢𝐭𝐲 𝐂𝐨𝐦𝐦𝐢𝐭𝐦𝐞𝐧𝐭 - TP-Link is a signatory of the U.S. Cybersecurity and Infrastructure Security Agency’s (CISA) Secure-by-Design pledge. This device is designed, built, and maintained, with advanced security as a core requirement.
3. Correct Frappe’s host_name
Frappe stores site-level settings in site_config.json, not a JavaScript file. In a conventional Bench layout, the file is under sites/<site-name>/site_config.json; packaged or managed installations may place it elsewhere. Locate the file for the site that is generating the PDF and preserve the existing JSON syntax.
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 →Add or update the host_name property with an address reachable from the wkhtmltopdf process:
{
"host_name": "http://127.0.0.1:8000"
}A Frappe user reported that the loopback value above solved a local setup. It is correct only when wkhtmltopdf runs on the same machine and the Frappe service listens on port 8000 there. If the renderer is in another container, 127.0.0.1 points back to that container, not to the web container.
Choose the address by deployment
| Where wkhtmltopdf runs | Candidate host_name |
Required condition |
|---|---|---|
| Same host as the Frappe web process | http://127.0.0.1:8000 |
The service listens on that loopback port from the renderer’s process. |
| Separate process or host on a private network | http://192.0.2.10:8000 (example address) |
Use the actual private IP, open port and route for your deployment. |
| Containerized Bench | http://frontend:8000 (example service name) |
The name must resolve on the container network and expose the Frappe service port. |
| Production behind a proxy | https://erp.example.com |
The production renderer must resolve the domain, reach the HTTPS port and receive the expected certificate and response. |
The names and addresses in the table are patterns, not values to copy blindly. A forum report from a container deployment used an internal frontend address; the exact hostname is deployment-specific. Select the value that matches the process location, DNS, port, scheme and routing you verified in the previous step.
Apply the change safely
- Back up
site_config.jsonbefore editing it. - Change only
host_nameunless you have a separate reason to alter another setting. - Validate that the file remains valid JSON and that the URL has the correct scheme and port.
- If your process manager caches configuration, restart the Frappe web/PDF worker according to your deployment procedure.
- Generate the same document again and retain the new stderr output for comparison.
4. Verify every URL used by the generated page
Changing host_name can make the main document reachable while leaving a failing asset URL untouched. Inspect the generated HTML or template output for:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- absolute
http://orhttps://links pointing at an old domain; - ports that are exposed only inside another network;
- CSS, image or font hosts that the PDF worker cannot resolve;
- redirects to a login page, consent page or external service;
- mixed HTTP/HTTPS references that are blocked or routed differently.
Test the important asset hosts from the same renderer environment. If the document depends on private resources, make sure the request carries the authentication mechanism that the application expects, or render with URLs available to the worker. A valid top-level page does not guarantee that all of its dependencies are retrievable.
5. Separate network success from PDF layout
Once the handshake error disappears, check the actual PDF. A related support discussion describes formatting trouble remaining after a network workaround. That is a separate problem: missing CSS, inaccessible fonts, different media rules, page-break behavior and renderer limitations can all affect layout after retrieval succeeds.
Rank #3
- Dual band router upgrades to 1200 Mbps high speed internet (300mbps for 2.4GHz plus 900Mbps for 5GHz), reducing buffering and ideal for 4K stream
- Full Gigabit Ports - Gigabit Router with 4 Gigabit LAN ports, ideal for any internet plan and allow you to directly connect your wired devices
- Boosted Coverage - Four external antennas equipped with Beamforming technology extend and concentrate the Wi-Fi signals
- MU-MIMO technology - (5GHz band) allows high speeds for multiple devices simultaneously
- Access Point Mode - Supports AP Mode to transform your wired connection into wireless network, an ideal wireless router for home
Compare the new PDF with the browser view and inspect whether stylesheets, images and fonts loaded. Do not revert a correct network address merely because the visual result needs additional template or CSS work.
Local, container and production edge cases
Local development
Use loopback only when the PDF process and Frappe service share the host. Confirm the port with the service configuration and test it from the shell that launches wkhtmltopdf. If the service binds only to a different interface or port, use that reachable address instead.
Containers
Container DNS names and published host ports are not interchangeable. A service name may work between containers while the host’s localhost does not. Test from the PDF container, use the internal service name and port that are actually exposed there, and ensure the network policy permits the connection.
Production
For production, decide whether the renderer should use an internal route or the public domain. An internal route can avoid an unnecessary proxy or hairpin path, while the public domain may be the only address whose redirects and asset URLs match the generated document. Whichever you choose must resolve and connect from the production PDF worker and must serve the scheme and certificate expected by that hostname.
Common symptoms and fixes
| Symptom | Likely location of the problem | What to check |
|---|---|---|
Immediate SslHandshakeFailedError |
Renderer cannot reach or negotiate with the selected host | Run DNS and curl tests in the renderer environment; verify scheme, port and route. |
| Browser works, PDF worker fails | Different network namespace, DNS or firewall | Repeat the test inside the worker or container rather than on your workstation. |
127.0.0.1 works locally but not in production |
Loopback points to the wrong machine or container | Use a reachable private address, service name or production domain. |
| Connection refused or timeout after changing the host | Nothing is listening on that port, or the route is blocked | Confirm the listener, container port mapping, firewall and network policy. |
| Handshake error is gone but styles are missing | Asset retrieval or CSS/layout issue | Inspect stylesheet, font and image URLs separately and verify the resulting PDF. |
Error persists after host_name change |
A different resource is failing, or the value is not loaded | Confirm the edited site is the one generating the PDF, restart cached workers, and identify the exact resource in stderr and HTML. |
| Certificate warning appears during direct testing | Hostname, certificate chain or trust differs in the renderer environment | Validate the certificate for the exact hostname from that environment; do not treat bypassing verification as the fix. |
What not to do
- Do not assume that every occurrence is a TLS-certificate defect; the reports support a reachability and host-routing investigation, not one universal cause.
- Do not disable certificate verification as a first-line remedy. The available reports do not establish that it is safe or effective.
- Do not publish a loopback address as a universal production setting.
- Do not declare success solely because wkhtmltopdf exits cleanly; inspect the PDF and its external resources.
Operational checks for reliable PDF generation
Keep the renderer’s network path predictable. Use a hostname that remains resolvable from the worker, avoid unnecessary proxy or hairpin routes, and make sure the selected port is part of the deployment contract. Record the chosen host_name, the process location, renderer version and the URLs tested. After a container, DNS, proxy or certificate change, rerun the same checks before investigating template formatting.
When escalating an unresolved case, provide the complete stderr, wkhtmltopdf version, exact failing URL or resource, the execution location (local, container or production), the configured host_name, and the result of DNS and HTTP tests from that environment. That information distinguishes routing, authentication, certificate and layout issues without resorting to unsafe workarounds.
Free tools Windows power users keep installed
One-click scans. No signup required.
Or skip the browser setup
If your goal is a clean screenshot or PDF rather than preserving a wkhtmltopdf pipeline, ScreenshotNeo provides a website screenshot API and MCP server. It accepts a URL and returns PNG, JPEG, WebP or PDF; it is an alternative workflow, not a repair for a broken wkhtmltopdf installation.
Rank #4
- Dual-band Wi-Fi with 5 GHz speeds up to 867 Mbps and 2.4 GHz speeds up to 300 Mbps, delivering 1200 Mbps of total bandwidth¹. Dual-band routers do not support 6 GHz. Performance varies by conditions, distance to devices, and obstacles such as walls.
- Covers up to 1,000 sq. ft. with four external antennas for stable wireless connections and optimal coverage.
- Supports IGMP Proxy/Snooping, Bridge and Tag VLAN to optimize IPTV streaming
- Access Point Mode - Supports AP Mode to transform your wired connection into wireless network, an ideal wireless router for home
- Advanced Security with WPA3 - The latest Wi-Fi security protocol, WPA3, brings new capabilities to improve cybersecurity in personal networks
With a ScreenshotNeo API key, the one-call request is:
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 parameters and response details. The equivalent Python request is:
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}`);Before capture, ScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server exposes take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients.
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 problemsThe Free plan includes 1,000 shots per month with no card. Paid plans are Starter ($5 for 3,000 shots), Growth ($15 for 15,000), Pro ($39 for 60,000), Scale ($99 for 250,000) and Business ($249 for 1,000,000); yearly billing gives two months free, and every feature is included on every plan.
Sign up for ScreenshotNeo’s free 1,000 screenshots a month—no card required.
Frequently Asked Questions
Does changing host_name change the URL that customers use in their browsers?
No. It selects the address Frappe uses when constructing and fetching pages for server-side work; it does not change DNS, public links or the reverse-proxy configuration.
Why can the main page load while a font or image still fails?
wkhtmltopdf fetches each referenced resource independently. A successful document response does not prove that every stylesheet, font, image, script or redirect is reachable from the renderer.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows 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 reinstallWhat is the safest next step when the reported workaround does not apply?
Collect the renderer version, complete stderr, exact failing resource, execution location and DNS/HTTP test results from that location. Those details identify whether the remaining issue is routing, authentication, certificate trust or layout.
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.
