wkhtmltopdf Exit Code 1: Common Causes and Fixes

Exit code 1 does not identify a specific wkhtmltopdf problem. Save the complete stderr output, find the failed page or asset, and check that resource from the same machine and runtime that launched wkhtmltopdf. A PDF file may exist even when the process exits nonzero, so verify both the exit status and the PDF’s contents.

This guide walks through the common causes, a repeatable diagnostic process, and safe ways to handle errors. The exact fix depends on your command, stderr, HTML, wkhtmltopdf build, operating system, and network or file-access context.

1. Start with the complete error message

Look in stderr for lines such as Error: Failed to load ... and the text that follows due to network error. The error class and resource help narrow the search. Examples in reported issues include HostNotFoundError, ProtocolUnknownError, and ContentOperationNotPermittedError. These examples are useful clues, not a complete error taxonomy.

What stderr says or points to	First thing to investigate
`HostNotFoundError` or a named host	Name resolution, outbound access, proxy settings, redirects, and whether that host is reachable from the wkhtmltopdf environment.
`ProtocolUnknownError` or `about:blank`	Empty, malformed, or unsupported URLs in the HTML, CSS, or JavaScript-generated markup.
`ContentOperationNotPermittedError` or HTTP 403	The response, authorization, redirects, or restrictions on the named resource.
A local path, stylesheet, image, or script	Path resolution, permissions, and wkhtmltopdf’s local-file-access policy.
A PDF exists despite exit code 1	Whether the PDF is complete and whether any named assets or page content are missing.

Do not diagnose from the final “Exit with code 1” line alone. Preserve all earlier warnings and errors; they may name the failed resource.

2. Capture a useful, reproducible diagnostic

Record the exact command, full stderr, installed binary version, operating system and version, and whether a wrapper such as a language library launches the binary. Keep a small HTML input that reproduces the problem. These details help distinguish a bad URL from a packaging, path, or wrapper issue.

wkhtmltopdf --version
wkhtmltopdf --log-level info input.html output.pdf 2>wkhtmltopdf.stderr
status=$?
printf 'wkhtmltopdf exit status: %s\n' "$status"
cat wkhtmltopdf.stderr

Run this in the same container, account, and environment as the failing job. If the command is produced by a wrapper, capture the wrapper’s exact arguments and compare them with a direct invocation.

3. Fix remote host and network failures

When stderr names a host or remote URL, test that exact resource from the machine or container that runs wkhtmltopdf. Check DNS resolution, outbound connectivity, proxy configuration, redirects, and whether the resource requires authentication. A browser on your workstation may reach a URL that the server process cannot.

Copy the complete failed URL from stderr, including its scheme and path.
Request it from the wkhtmltopdf runtime environment and inspect the response and redirects.
Confirm that the main document and its dependent assets—such as CSS, scripts, images, or iframe content—are each reachable.
Correct the unavailable host, URL, proxy, or access configuration, then rerun and inspect the PDF.

A reported HostNotFoundError occurred in a document referencing remote assets and an iframe; it does not identify which individual resource caused that report. Use your own stderr to locate the failing resource.

4. Fix blocked local files and relative paths

For local HTML, resolve every linked stylesheet, script, image, and other file relative to the actual input location, or set an intentional base URL. Check that the process account can read each file and that the installed binary’s local-file policy allows it.

The CLI documents --disable-local-file-access, --enable-local-file-access, and --allow for specifying files that may be loaded. Prefer the narrowest access that works. Enabling broad local access for untrusted HTML can expose files on the machine to that input.

# Allow access only to a directory containing the intended assets.
wkhtmltopdf --allow /srv/report-assets /srv/reports/input.html /srv/reports/output.pdf

Use the paths appropriate to your deployment and confirm the exact syntax supported by the installed binary with wkhtmltopdf --extended-help. A Windows issue reported blocked CSS, JavaScript, and images followed by a protocol error for about:blank; inspect both the local-file policy and generated URLs rather than treating that one report as a universal diagnosis.

5. Check HTTP errors, SSL, authentication, and redirects

If stderr names an HTTPS resource, request that exact URL from the same runtime and inspect its actual response, redirect chain, and authentication requirements. An archived report describes an HTTP 403 and ContentOperationNotPermittedError in an SSL setup. That makes access and authorization worth checking; it does not establish that changing HTTPS to HTTP is a safe or general fix.

Also check whether a resource URL is generated dynamically and becomes empty or malformed. A valid top-level page can still fail because an image, stylesheet, iframe, header, or footer URL returns an error or cannot be loaded.

6. Investigate protocol errors and wrapper behavior

For ProtocolUnknownError, inspect the HTML and CSS for unsupported or malformed schemes and empty URLs. If JavaScript generates markup, inspect the generated result as well as the source template.

One issue report describes a Python pdfkit.from_string(html, False) call failing while writing to a file path worked in that reporter’s setup. Treat this as a wrapper-specific clue. Compare the wrapper’s generated command and input with a direct wkhtmltopdf invocation before concluding that output-to-memory is generally broken.

7. Use load-error options with care

The CLI documents --load-error-handling for pages that fail to load, with abort, ignore, and skip as handlers; the documented default is abort. It also documents --load-media-error-handling for media failures, with ignore as the documented default.

# Example only: ignoring a page-load failure may produce incomplete output.
wkhtmltopdf --load-error-handling ignore input.html output.pdf

Use an ignore or skip handler only when the missing content is acceptable. These options do not guarantee that every network error will be suppressed or that the process will exit successfully. After changing one option, check stderr, exit status, and the resulting PDF for missing content.

8. Follow a repeatable troubleshooting sequence

Save the full stderr and exact command, including arguments supplied by any wrapper.
Record wkhtmltopdf --version, binary or package provenance, operating system and version, and runtime identity.
Find each failed-load line and identify whether it names the main page or a dependent resource such as CSS, JavaScript, an image, iframe, header, or footer.
Test the named URL or local path from the same environment that launches wkhtmltopdf.
Fix the underlying cause: host lookup or reachability, response or authorization, malformed URL, relative path, permissions, or local-file policy.
If testing error handling, change one variable at a time. Rerun, inspect stderr and exit status, and verify the PDF’s visual and textual content.
Reduce the failure to a small HTML file plus only the assets needed to reproduce it.

The official support guidance asks for the version, operating system and version, a detailed description, and a reproducer. Include those details when seeking help.

9. Version, security, reliability, and cost notes

Version and build

The project downloads page in the reviewed research lists wkhtmltopdf 0.12.6 as its stable series and gives June 11, 2020 as the release date. This does not mean every operating-system package has the same build or behavior. Check the version and provenance of the binary actually running before applying version-specific advice.

Security

wkhtmltopdf’s 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!” Treat HTML, JavaScript, and local-file permissions as security-sensitive. Avoid enabling access to broad filesystem locations when the input is untrusted.

Reliability

A nonzero exit code is a failure signal even if an output file exists. Check that the PDF opens, has the expected pages, and includes required content. If a missing resource is acceptable and you elect to ignore it, make that decision explicit and keep validating the output.

Performance and cost

The reviewed sources provide no benchmark or general cost figure for wkhtmltopdf. In practice, remote dependencies can add network waits and failure points; identifying and testing the actual failed resource is more useful than assuming a performance cause from exit code 1 alone. Keep inputs small when reproducing a failure so each rerun is easier to inspect.

10. Or skip the browser setup

If your task is to capture a website as an image or PDF, ScreenshotNeo is a website screenshot API and MCP server. Its GET endpoint accepts a URL; see the 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

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, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free account and start with 1,000 screenshots a month, no card required.

11. Frequently asked questions

Does exit code 1 always mean no PDF was created?

No. Some reported runs returned a PDF alongside a nonzero status. Check that the file is complete and contains the expected content.

Can I ignore a failed resource?

Sometimes, if the missing content is acceptable. Use the documented handler deliberately, then verify stderr, status, and output.

What information should I include in a bug report?

Provide the binary version and provenance, operating system and version, full command and stderr, a detailed description, and a small reproducer with only the necessary assets.

Is changing an HTTPS URL to HTTP a fix?

The reviewed evidence does not support that as a general fix. Check the actual response, redirects, and authorization for the HTTPS resource.