How to Fix wkhtmltoimage Cannot Connect to Host Errors

A wkhtmltoimage “cannot connect to host” message does not, by itself, prove that the main website is down. The failed load may be the page itself, or a referenced image, stylesheet, font, script, or other resource. First identify the exact URL or path named in stderr; then check whether it is local or remote, validate it, and investigate the matching access or network settings.

The options below are documented by the wkhtmltoimage manual and the project usage documentation. Exact behavior can vary by binary version, operating system, package, and wrapper.

1. Capture the error and identify the failed load

Before changing flags, save enough information to distinguish an input problem from an environment problem. Keep credentials and tokens out of shared logs.

The complete command, including all options, with secrets redacted.
The output of wkhtmltoimage --version.
All stderr output and the exit code.
Operating system, container or service context, and whether a wrapper invokes the binary.
Whether the input is a remote URL or a local HTML file.
The exact URL or path that failed, if stderr identifies one.

Separate the top-level document from its dependencies. A page can load successfully while one of its images or stylesheets fails. One upstream report described a missing relative image followed by an about:blank / ProtocolUnknownError message; that report is an example, not a universal interpretation of the suffix. See upstream issue #4408.

2. Check the URL, path, and relative-resource base

Inspect the failing resource, not just the command’s first argument. Check that the scheme is correct (http, https, or a correctly formed file: URL), the hostname and port are right, and the requested path exists. For a relative image or stylesheet URL, confirm that the HTML document’s base location resolves it where expected.

For local resources, confirm the file exists and that its path syntax matches the operating system. Windows paths and file URLs are easy to form incorrectly. The explicitly named input HTML file and other local files it references are distinct: a local-file policy may block a dependency even when the input file itself is accepted. Upstream issue #1639 discusses historical Windows path behavior.

If a remote page redirects, inspect the destination too. The original host may be reachable while the redirected host or a referenced asset host is not.

3. Allow required local files narrowly

When the failed resource uses a local path, check local-file access before changing DNS or proxy settings. The documented controls include --allow <path> to permit access to a path, --enable-local-file-access to enable local access, and --disable-local-file-access to restrict it. Grant only the files or directories the render needs when practical.

wkhtmltoimage --allow /srv/site/assets file:///srv/site/index.html /tmp/page.png

Or, when broad local access is necessary for the job:

wkhtmltoimage --enable-local-file-access file:///srv/site/index.html /tmp/page.png

Use the path form appropriate to your operating system and verify the exact binary’s supported syntax. Reports around version 0.12.6 describe changed defaults and wrapper-specific option mapping; they do not establish one behavior for every package. The go-wkhtmltopdf wrapper discussion is version- and wrapper-specific. Another Windows report found that the enable flag alone did not resolve the reported access problem. See upstream issue #5210.

4. Check remote network access from the renderer’s environment

If the failing resource is remote, test from the same host, container, service account, and runtime environment that launches wkhtmltoimage. A URL that loads on a developer laptop may be unreachable from a production container. Check hostname resolution, outbound firewall rules, proxy settings, TLS certificates, and redirects to other hosts. This dossier’s sources document proxy options but do not establish a universal set of operating-system diagnostic commands.

The command-line documentation lists --proxy, --proxy-hostname-lookup, and repeatable --bypass-proxy-for options. Consult the installed binary’s help and the manual for the syntax supported by that build. Option reference.

wkhtmltoimage --proxy http://proxy.example:8080 https://example.com /tmp/page.png

proxy.example:8080 is a placeholder; replace it with your configured proxy or omit the option when no proxy is required. If only some destinations should bypass the proxy, use the documented bypass option and validate its syntax against your version. Do not add proxy settings to a local-file problem without evidence that the failing resource is remote.

5. Choose how load errors should be handled

--load-error-handling and --load-media-error-handling control what wkhtmltoimage does when a page or media resource fails to load. The documented policies are abort, ignore, and skip. They are handling policies, not connectivity fixes: they cannot make a missing file exist, repair a malformed URL, or create a network route.

Policy	Use when	What it does not do
`abort`	A failed load should stop the capture.	It does not identify or repair the failing resource.
`skip`	A failed resource can be omitted.	It does not restore the omitted content.
`ignore`	You want the renderer to attempt to continue despite a load failure.	It does not guarantee a complete image or a successful exit code.

For example, to request that media load errors be ignored:

wkhtmltoimage --load-media-error-handling ignore https://example.com /tmp/page.png

Check the resulting image and exit status. In the report in issue #4408, ignore-related settings did not prevent exit code 1. The result depends on the actual failure and build.

6. Retest one change at a time

Keep the original command and stderr as a baseline.
Change one input or setting: correct a URL, fix a local path, grant a needed directory, or update the proxy configuration.
Repeat the same capture in the same runtime environment.
Compare stderr, exit code, and output. Confirm that the expected content appears in the image.
Record the working binary version and invocation so a wrapper or deployment change does not silently remove the setting.

Changing one variable at a time makes it easier to tell whether the fix addressed the cause or merely changed how the failure is reported.

7. Common errors and fixes

Symptom	Likely cause to check	Next step
“Cannot connect” or network error, but the main page appears	A dependent image, stylesheet, font, or script failed.	Find the exact resource URL in stderr; validate its URL and reachability separately.
`ProtocolUnknownError` after a missing relative image	The relative resource may have resolved to an invalid or unsupported location.	Check the HTML base URL and resource path. Treat this wording as a clue, not a definitive diagnosis.
Local HTML opens, but local images or CSS are absent	Local-file access is restricted, or a referenced path is malformed.	Verify the path and use a narrow `--allow` path or the required local-access setting.
`--enable-local-file-access` has no effect	The path may be wrong, the option may be unsupported or misplaced, or a wrapper may not pass it through.	Check version, command syntax, wrapper configuration, and the exact denied resource.
Works on a workstation but fails in a container or service	Different DNS, outbound network, proxy, certificates, filesystem, or service-account permissions.	Reproduce checks from the renderer’s actual runtime context.
Page redirects before failing	The redirect destination may be inaccessible or require different network access.	Inspect the final destination and its dependent assets.
Ignore or skip is set, but the command still exits with an error	Error policy does not guarantee a successful exit or complete output for every failure.	Fix the underlying resource where possible; inspect stderr, exit status, and image.

8. Performance, reliability, and cost considerations

For reliable captures, remove avoidable failed dependencies, keep local access scoped, and run with the same network and filesystem permissions in development and production. A page with many remote dependencies has more opportunities for an individual resource to fail; a partial render can therefore look like a connection problem even when the document loaded. The cited documentation does not provide universal performance benchmarks or a fixed timeout recommendation for this error.

When diagnosing intermittent failures, preserve the complete stderr and exit status for each run, plus the renderer version and runtime context. Separate a missing optional asset from a failed critical stylesheet or document. Choose skip or ignore only when incomplete output is acceptable to your use case, and inspect the image rather than treating a generated file as proof of a successful page render.

9. Or skip the browser setup

If maintaining a rendering binary, its local-file policy, and its network path is not a fit, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a screenshot or PDF. See the ScreenshotNeo API documentation for parameters.

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}`);

ScreenshotNeo accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account for 1,000 screenshots a month, with no card required.

10. FAQ

Does “cannot connect to host” always mean the website is down?

No. The failed load may be a dependency, a local file, a redirect destination, or a remote host. Identify the specific resource before diagnosing the main site.

Should I always enable local-file access?

No. First establish that the failed resource is local. Prefer allowing only the required directory when that is sufficient.

Will `ignore` make the screenshot complete?

No. It changes error handling; a missing resource can remain missing, and some failures can still produce a nonzero exit status.

Why does this behave differently under a wrapper?

A wrapper can map options to a page or object differently from the command line, and its bundled binary may differ from the system binary. Check the version and effective invocation used by the wrapper.

Where can I confirm the available flags?

Check the installed binary’s help and the wkhtmltoimage manual. Downstream builds and wrappers may differ from the referenced documentation.