wkhtmltopdf Blocked by SSL Error on HTTPS Pages: How to Fix It

An SSL error from wkhtmltopdf does not identify one universal bug, and there is no general-purpose flag that makes every HTTPS page work. First determine which request failed: the main document, a redirect target, or a linked stylesheet, image, font, script, or iframe. Then inspect that exact endpoint’s TLS handshake and access response. The documented --ssl-crt-path and --ssl-key-path options provide a client certificate and key; they are for servers that require client-certificate authentication, not for bypassing server-certificate checks.

This guide walks through the diagnosis, explains the relevant options, and covers when to change the endpoint, the renderer, or the way the PDF is produced.

1. Capture the error and identify the failed URL

Before changing flags, preserve the full standard error output and record the rendering environment. Version labels alone may not identify the same build: package source, operating system, and whether the binary uses patched Qt can matter.

wkhtmltopdf --version
wkhtmltopdf --extended-help

Run the exact failing command with stderr saved:

wkhtmltopdf https://example.com/report report.pdf 2>wkhtmltopdf.log

Review the complete log, not just the line containing “SSL error.” Note the URL named in the message and whether it is the page, a redirect destination, or a dependent resource. A historical report against version 0.12.4 described HTTPS stylesheets and images failing while HTTP equivalents worked. That report is an example of a resource-level failure, not proof that HTTP is a safe workaround or that all versions share the same cause. [Issue #4462]

2. Test the exact host’s TLS handshake

Use OpenSSL’s diagnostic client against the hostname and port in the failed URL. Include SNI with -servername, which lets the server select the expected certificate when multiple sites share an address.

openssl s_client -connect example.com:443 -servername example.com

For a clearer verification summary on OpenSSL versions that support it, add -verify_return_error:

openssl s_client -connect example.com:443 -servername example.com -verify_return_error

Check whether the handshake completes, what certificate chain is presented, and whether verification succeeds. OpenSSL documents s_client as a tool to establish and inspect SSL/TLS connections; a failed handshake can have multiple causes, so the output needs interpretation in context. [OpenSSL s_client documentation]

Repeat this check for the actual host of the failed resource. A page can load while a third-party font or image host has a separate certificate, network, proxy, or access problem. If the page redirects, test the final destination as well as the initial URL.

3. Check redirects, network access, and dependent resources

1. Inspect redirects. Confirm that every redirect destination is reachable from the rendering host and uses a valid certificate chain. Check for redirects to a login page, blocked region, or URL that needs credentials.
2. Check DNS and outbound connectivity. Verify the renderer’s host resolves the names and can connect to each endpoint on the needed port.
3. Check proxy settings. Review environment proxy variables and any explicit proxy configured for wkhtmltopdf. A proxy can change which host is reached or how TLS is negotiated.
4. Test each failing asset URL. Inspect the CSS, image, font, script, or iframe URL named in the log. Confirm its response and certificate independently.
5. Check access controls. A TLS warning can appear alongside an HTTP error or denied operation. One historical report for 0.12.6 with patched Qt on Ubuntu Focal included “Warning: SSL error ignored” followed by a 403 and ContentOperationNotPermittedError. That combination shows why the status and requested URL matter; it is not a general explanation for SSL errors. [Issue #4897]

A browser successfully opening a page does not establish that the installed renderer can fetch the same page and every dependency. The browser may use a different TLS stack, trust store, proxy, credentials, or network path.

4. Use the SSL options only for client-certificate authentication

The usage reference documents --ssl-crt-path and --ssl-key-path for supplying a client certificate and private key. The certificate file may also contain intermediate CA and trusted certificates. These options are appropriate when the remote server requires a client certificate to authenticate the caller. [wkhtmltopdf command-line usage reference]

wkhtmltopdf \
  --ssl-crt-path /path/to/client-cert-and-chain.pem \
  --ssl-key-path /path/to/client-key.pem \
  https://example.com/report report.pdf

Protect the private key and ensure the rendering process can read it. Do not pass these flags expecting them to accept an invalid server certificate or add support for a TLS configuration missing from an older Qt WebKit build. The documented options do not claim to do either.

5. Understand load-error handling

--load-error-handling controls what the converter does after a page load fails. The documented behaviors are abort, ignore, and skip. This setting changes the response to a failed load; it does not repair the TLS handshake or make the connection valid. [wkhtmltopdf command-line usage reference]

# Abort when a page load fails (documented default behavior)
wkhtmltopdf --load-error-handling abort https://example.com/report report.pdf

# Continue despite a page load failure; the PDF may omit content
wkhtmltopdf --load-error-handling ignore https://example.com/report report.pdf

# Skip a page that fails to load in a multi-page conversion
wkhtmltopdf --load-error-handling skip page1.html page2.html combined.pdf

Use ignore only when a partial PDF is acceptable and you have a way to detect missing content. It is not a fix for a broken document. Confirm the exact option behavior supported by your installed build with wkhtmltopdf --extended-help.

6. Choose a fix based on the failing layer

Finding	Next step
The server requires a client certificate	Obtain the correct certificate and key from the service owner, then configure the documented client-certificate options.
The main host or redirect destination fails the independent handshake	Resolve the host’s certificate chain, TLS configuration, DNS, network, or proxy problem with the endpoint owner or administrator.
The main page works but a linked asset fails	Fix access to that asset host, provide the required authentication, or remove or replace the dependency if it is not needed in the PDF.
The handshake works independently but this renderer still fails	Check the exact binary build, OS libraries, proxy path, and renderer compatibility. Reproduce with the actual document before changing tools.
The request succeeds but returns 403 or another access error	Fix authorization, cookies, headers, or server policy. Treat this as an HTTP/access problem, even if the log also contains an SSL warning.
A partial PDF is explicitly acceptable	Consider --load-error-handling ignore or skip for the appropriate page, then verify the output for missing content.

Do not switch HTTPS resources to HTTP as a routine workaround: that can expose requests and content to interception and may fail where the site requires HTTPS. Do not routinely disable certificate verification. If you cannot safely change the endpoint and the renderer’s TLS behavior is incompatible, evaluate another renderer against the actual document.

7. When to consider another renderer

The wkhtmltopdf project status page points readers toward WeasyPrint or commercial Prince for controlled report generation, and Puppeteer or a wrapper for pages that require dynamic JavaScript. These are options to evaluate, not guaranteed fixes. Compare TLS behavior, JavaScript requirements, deployment dependencies, output fidelity, maintenance, and licensing with a representative document; the sources here do not provide comparative benchmark results. [wkhtmltopdf project status page]

The same status page warns against rendering untrusted HTML because user-supplied HTML or JavaScript can compromise the host. Sanitize untrusted input and isolate the rendering process. Review current maintenance status and versions before selecting a replacement; the cited status page is old.

Or skip the browser setup

For a clean capture of a web page, ScreenshotNeo provides a website screenshot API and MCP server. Its API returns a screenshot or PDF from one GET request. See the API documentation for the available options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

• Cookie banners are accepted and 60+ known consent platforms, newsletter popups, and chat widgets are removed before capture; each step can be turned off.
• Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers report the page verdict and billing status.
• An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
• The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

Sign up free for 1,000 screenshots a month, no card required.

Troubleshooting checklist

• Only a vague SSL warning is available: rerun with full stderr logging and capture the exact requested URL.
• The URL in the log is not the page URL: diagnose the named redirect or dependent asset host instead.
• s_client reports a verification or handshake failure: inspect the chain, SNI hostname, endpoint TLS configuration, and network path with the service owner.
• s_client connects, but wkhtmltopdf fails: verify the precise build and runtime dependencies, then reproduce with the smallest document that still fails.
• The log says “SSL error ignored” but the PDF is incomplete: inspect subsequent HTTP status and resource errors; ignoring an error does not mean the resource loaded.
• The PDF succeeds with ignore but content is missing: fix the failed request or accept the omission explicitly; load-error handling does not restore the content.
• It works on a laptop but fails on a server: compare DNS, firewall, proxy variables, trust store, credentials, and the installed package build between environments.
• A certificate flag did not help: use those flags only when the server expects client-certificate authentication; they are not a general server-certificate bypass.

Performance, reliability, and cost

Repeated TLS failures can waste conversion time, especially when the renderer waits on several resources or retries are handled by the surrounding application. Identify the failing URL first, then avoid blind retries that repeat the same handshake or access failure. If you use cache or a retry layer around rendering, distinguish a successful document from a partial output and record the failed resource and final URL.

There is no benchmark in the sources for how much time a renderer change will save or how often a particular fix works. Account for the operational cost of maintaining the binary, its system dependencies, network access, certificates, and any replacement runtime. Validate reliability with representative pages that exercise redirects, required assets, authentication, and JavaScript behavior.

FAQ

Does a browser loading the URL prove wkhtmltopdf should load it?

No. The browser and renderer can differ in TLS implementation, trust store, proxy, credentials, and network route. Test from the renderer’s environment.

Should I use --ssl-crt-path to trust the website certificate?

No. It supplies a client certificate for server-side client authentication. It is not documented as an option to trust or bypass a website’s server certificate.

Can --load-error-handling ignore fix an SSL error?

No. It changes how conversion proceeds after a failed load. The resulting PDF may be missing the page or resource.

Is HTTP a safe fallback for a failing HTTPS image or stylesheet?

Not as a general fix. It can weaken transport security and may not work at all. Resolve the HTTPS endpoint or remove the dependency when appropriate.

Is an alternative renderer guaranteed to solve it?

No. Test its TLS behavior, document requirements, deployment needs, output, and licensing against the actual page before migrating.