Why Does wkhtmltoimage Show a Blank Page? Fixes for Common Causes

Short answer: wkhtmltoimage shows a blank page when visible content was not available to its renderer at capture time, or when the output geometry excludes that content. Check the input page, JavaScript and timing, local-file permissions, failed page or media requests, then viewport and crop settings. Waiting longer or ignoring a load error can help diagnose a case, but neither repairs an inaccessible resource or guarantees a complete render.

1. Confirm what wkhtmltoimage received

wkhtmltoimage converts an HTML page into an image. First determine whether the problem is in the page or in the conversion:

Open the same URL or local HTML file in a current browser on the machine that runs the converter.
Check whether the expected content appears, including after scripts finish.
For a remote URL, check redirects, authentication, proxy access, and whether the converter’s host can reach it.
For a local file, confirm the file exists and inspect every referenced stylesheet, script, image, and font path.
Run wkhtmltoimage with its output visible in the terminal and save its warnings and errors.

If the browser also shows a blank page, investigate the input or its access requirements first. If the browser shows the expected content, use the following checks to isolate renderer settings and compatibility.

2. Check JavaScript and render timing

JavaScript is enabled by default in documented settings, but it can be disabled explicitly. Pages that insert content asynchronously may not have rendered it by the time the capture occurs. The CLI offers a fixed delay and a window-status wait; these are diagnostic controls, not a guarantee that a script or unsupported page feature will work. [Debian wkhtmltoimage manual, project settings documentation]

wkhtmltoimage --enable-javascript --javascript-delay 2000 input.html output.png

Replace 2000 with a measured delay appropriate to the page. If the page sets a known window status after its content is ready, try that condition instead:

wkhtmltoimage --enable-javascript --window-status ready input.html output.png

To test whether scripts are involved, compare a JavaScript-enabled capture with one that disables scripts. A disabled-script capture can help distinguish static markup from script-generated content; it is not a fix for a page whose content depends on JavaScript.

wkhtmltoimage --disable-javascript input.html without-js.png

For script errors, enable JavaScript debugging if supported by the installed build, and inspect the command output. A longer delay will not fix script errors, redirects, authentication failures, or features the renderer cannot handle. One historical issue report describes a redirect/interstitial result that remained wrong after adding a delay; it is an example, not a universal diagnosis. [issue #2346]

3. Verify local-file access and paths

Local HTML can reference resources such as file:///... images or stylesheets. The converter’s local-file-access policy can prevent it from reading them. Verify paths and filesystem permissions, then grant only the access the input needs. The CLI documents both broad local-file access and a scoped --allow path. [Debian manual]

# Permit access to one resource directory
wkhtmltoimage --allow /srv/site/assets input.html output.png

# Use only when the input genuinely needs broad local-file access
wkhtmltoimage --enable-local-file-access input.html output.png

Check that the paths are valid from the process’s environment, not just from your interactive shell. Containers, service users, and deployment hosts may see different files and permissions.

A reported 2019 case used --disable-local-file-access while the HTML referenced a local image. The log included a blocked-file warning and a failed load. This is a concrete example to check local-file policy; it does not mean every missing image makes the entire output blank. [issue #4408]

4. Diagnose failed page and media requests

Page navigation and embedded objects such as images have separate load-error settings. Inspect the log and test the actual resource URLs from the machine running wkhtmltoimage. Confirm DNS, TLS, proxy settings, authentication, and HTTP responses where relevant. A setting that tells the converter to skip or ignore a failed object changes error handling; it does not make an inaccessible URL load or restore missing content.

The project documents abort, skip, and ignore behavior for failed objects. In particular, ignore means trying to add the object to output; it is not a promise of successful rendering. Page-load and media-load controls are separate, so identify which request failed before changing either. [project settings documentation, Debian manual]

# Example diagnostic run: keep output visible and test a longer render wait
wkhtmltoimage --javascript-delay 2000 https://example.com output.png

Use the manual for the exact option names and defaults in your installed version. Do not treat --load-error-handling ignore or a media-error setting as a general blank-page switch: an issue report found that ignore/skip settings did not resolve its particular protocol error. [issue #4408]

5. Rule out width, height, crop, and zoom

A page may have rendered outside the selected area. Inspect the command for width, height, crop coordinates and dimensions, and zoom. The manual describes width as a guide unless smart width is disabled. Temporarily remove crop and zoom overrides and capture a larger area to see whether the content exists beyond the original bounds. [Debian manual]

# Try a wider, uncropped capture to test geometry
wkhtmltoimage --width 1400 https://example.com wider.png

Once content is visible, restore your intended dimensions and adjust one geometry option at a time. Width and height settings are not a remedy for a page that never loaded.

6. Check image loading and output format

Confirm image loading is enabled if images are part of the expected result. Test an output format supported by your installed build and use a matching filename extension. The manual and project settings list format and image-loading controls; available formats and options can vary by build. [Debian manual, project settings documentation]

wkhtmltoimage --format png https://example.com output.png

If the file exists but appears empty, check its dimensions and size with your usual image tools, then compare with a simple static page. This separates an output-file or format issue from a page-specific rendering problem.

7. Use a minimal decision path

What you observe	Likely layer to inspect	Next step
Browser is blank too	Input, redirect, access, or page error	Resolve the page response before changing capture options.
Static text appears but dynamic content is missing	JavaScript or timing	Enable scripts, inspect errors, then try a measured delay or known window status.
Local styles or images are missing	Local-file policy or paths	Check paths and permissions; scope access with `--allow` where possible.
Terminal reports a failed URL or object	Page-load or media-load failure	Test that URL from the converter host; fix reachability or authentication.
Content is present in a larger capture	Viewport, crop, or zoom	Adjust the geometry settings incrementally.
Simple pages work but this page does not	Renderer compatibility or page complexity	Reduce the page to a reproducible case and compare with a renderer that supports its requirements.

8. When configuration changes do not help

Check the converter version and platform, then reproduce with a small HTML file that contains only the relevant markup and scripts. The wkhtmltopdf repository is archived and read-only. Its issue index includes reports titled “HTML page turns completely white/empty” and “Vanilla Javascript won’t render”; those reports show that users have encountered such symptoms, but issue titles are not official root-cause analyses and do not establish a universal fix. [project issue index]

If the page relies on modern browser behavior or complex scripts, a configuration tweak may not be enough. Compare the result with a renderer that supports the page’s requirements. Keep the source URL, converter version, command, warnings, and a minimal reproduction together when diagnosing or replacing the renderer.

Or skip the browser setup

For a screenshot workflow where you do not want to install and tune a local renderer, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It returns PNG, JPEG, WebP, or PDF from a GET request. Its clean-shot flow accepts cookie and consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf. Every feature is available on every plan: 1,000 shots per month are free with no card; paid plans start at $5 for 3,000 shots. 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}`);

Performance, reliability, and cost notes

Performance: A longer JavaScript delay increases the time each conversion waits. Use a known readiness condition when the page exposes one, and avoid increasing waits without evidence that content arrives late.
Reliability: Separate navigation, script execution, local-file access, media requests, and geometry in diagnosis. Ignoring a failure does not repair its cause. Keep logs and a reproducible input when comparing environments.
Cost: The research sources do not establish wkhtmltoimage pricing or provide performance benchmarks. Account for your own compute and maintenance costs. ScreenshotNeo’s published plans in the product information include 1,000 free monthly shots, then Starter $5 for 3,000, 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.

FAQ

Does `--javascript-delay` always fix a blank screenshot?

No. It only waits a specified time. It cannot fix an inaccessible page, script error, failed resource, or renderer incompatibility.

Should I use ignore for every load error?

No. First identify whether page navigation or an embedded object failed. Ignore behavior does not recover the missing resource and may still leave incomplete output.

Why does local HTML work in my browser but not in the command?

The converter process may have different file permissions or local-file-access settings. Check referenced paths from that process and grant only the access needed.

Is a blank result proof that the image format is unsupported?

No. Check the command output, dimensions, and a simple page in a supported format before attributing the symptom to format handling.