ScreenshotNeo

BlogHow-to

How to Fix wkhtmltoimage Capturing Only a Bar Instead of the Full Page

Diagnose bar-only wkhtmltoimage captures with dimension checks, viewport fixes, JavaScript timing, lazy loading tests, and reliable alternatives.

By the ScreenshotNeo team30 September 20267 min read

How to Fix wkhtmltoimage Capturing Only a Bar Instead of the Full Page

Direct answer: a bar-only image usually means wkhtmltoimage calculated or received a very short capture height, or the page itself is clipping content through fixed heights, overflow rules, viewport breakpoints, JavaScript timing, or lazy loading. First record the output pixel dimensions and your wkhtmltoimage version. Then test an explicit width, height, and JavaScript delay while checking the page layout.

The exact cause cannot be confirmed without the page URL, command, output dimensions, binary version, and logs. Work through the checks below in order.

1. Inspect the output dimensions first

Use an image tool to inspect the PNG dimensions. If the file is only a few pixels or a few dozen pixels high, the capture viewport is short. If the file has the expected height but the visible content is only a strip, investigate CSS, responsive layout, JavaScript, or lazy loading.

# ImageMagick
identify page.png

# GraphicsMagick
 gm identify page.png

# Python (Pillow)
python - <<'PY'
from PIL import Image
im = Image.open("page.png")
print(im.size)
PY

wkhtmltoimage documents screen height as calculated from page content by default and provides explicit --height and --width options. See the Ubuntu wkhtmltoimage manual.

2. Run a controlled diagnostic capture

Start with a known width, a deliberately tall height, a short delay, and JavaScript diagnostics:

A controlled URL, viewport, and readiness sequence produces a complete page image instead of a short strip.
A controlled URL, viewport, and readiness sequence produces a complete page image instead of a short strip.
wkhtmltoimage \
  --debug-javascript \
  --width 1280 \
  --height 3000 \
  --javascript-delay 1500 \
  'https://example.test/page' \
  page-diagnostic.png

The height and delay above are diagnostic values, not universal settings. Compare the resulting pixel dimensions and visible content with the original capture. If this produces a tall file, make the smallest option change that fixes your real command.

3. Check CSS that can reduce the visible page to a bar

A taller screenshot cannot reveal content that the page layout clips. Inspect the target page in a normal browser and look for:

  • Fixed-height wrappers such as height: 40px around the main content.
  • overflow: hidden or overflow: clip on a parent element.
  • Absolutely positioned content outside the document flow.
  • A child using height: 100vh when the capture viewport is short.
  • Responsive rules triggered by the chosen width.
  • A horizontal navigation or notification bar covering the rest of the page.

Use browser developer tools to disable suspicious height and overflow declarations. If the page then renders normally, fix the page CSS or inject a narrowly scoped override for capture.

wkhtmltoimage \
  --width 1440 \
  --height 4000 \
  --custom-header 'User-Agent' 'Mozilla/5.0' \
  'https://example.test/page' \
  page.png

A custom user agent is only useful when the site serves different markup to bots or small clients. Do not assume it fixes a layout clipped by CSS.

4. Test viewport width and responsive breakpoints

Viewport width can switch the page into a mobile or tablet layout. A layout that is full height at 1440 pixels may collapse into a navigation bar at a narrow width, or the reverse. Capture the same URL at several widths and compare dimensions:

for width in 768 1024 1280 1440; do
  wkhtmltoimage \
    --width "$width" \
    --height 3000 \
    --javascript-delay 1000 \
    "https://example.test/page" \
    "page-${width}.png"
done

The project issue archive contains an individual report involving --viewport-size, custom scrollbars, and CSS overflow. Treat that report as a diagnostic lead rather than proof that the option resolves every bar-only capture.

5. Account for JavaScript rendering time

If the page is an application shell, its content may not exist when wkhtmltoimage takes the screenshot. The --javascript-delay option waits after page load; the settings reference names the corresponding setting load.jsdelay.

wkhtmltoimage \
  --width 1280 \
  --height 3000 \
  --javascript-delay 3000 \
  --debug-javascript \
  'https://example.test/app' \
  app.png

Use a delay as a diagnostic first step. When you control the page, make readiness deterministic instead: render the content server-side, expose a stable completion state, or ensure the required data request finishes before capture.

Record the executable version before relying on timing flags:

wkhtmltoimage --version
wkhtmltoimage --extended-help | less

A historical issue documents a problem with --javascript-delay and --window-status in version 0.12.2, marked fixed in milestone 0.12.2.1. That is version-specific evidence, not a guarantee for every later build. Another issue involving window-status waiting on a JavaScript-heavy page was closed as invalid, so --window-status is not a universal readiness signal.

6. Check lazy-loaded content

Images, charts, maps, and application panels may load only after they enter the visible viewport. A project report records images that failed to load when visibility was required. Test the page by scrolling through it in a browser and watching the network panel. If content appears only after scrolling, a single initial capture may never trigger it.

Possible fixes include:

  • Use a page mode that renders the complete content before capture.
  • Change the application so important content does not depend solely on an intersection observer.
  • Replace lazy image placeholders with regular image URLs for the capture route.
  • Capture a purpose-built print or export page.

Do not treat lazy loading as confirmed without reproducing it on the specific page.

7. Use JavaScript diagnostics and a minimal reproduction

Keep the exact command and stderr output. Then compare the target with a minimal local page:

cat > /tmp/capture-test.html <<'HTML'
<!doctype html>
<html>
  <body style="margin:0">
    <div style="height:2400px;background:linear-gradient(#fff,#9cf)">
      Test content
    </div>
  </body>
</html>
HTML

wkhtmltoimage --debug-javascript --width 1280 --height 3000 \
  file:///tmp/capture-test.html test.png
identify test.png

If the local page is tall but the target is a bar, focus on the target’s CSS, JavaScript, resources, or response headers. If both are short, focus on the installed binary and command options.

8. Common symptoms and fixes

Symptom Likely area What to do
Output file is physically short Calculated or explicit height Inspect dimensions; set a test --height; check document content height.
File is tall but content is clipped CSS layout Inspect fixed heights, overflow, positioning, and viewport breakpoints.
Only a header or navigation bar appears JavaScript or responsive layout Increase width, add a diagnostic delay, inspect console output, and compare with a static page.
Images or charts are missing Lazy loading or failed resources Check network requests and whether scrolling triggers the resource.
Delay appears ignored Binary behavior or version Record wkhtmltoimage --version; compare help output and test another supported build.
Different machines produce different results Fonts, binary, viewport, or network Pin the binary, fonts, width, user agent, and readiness conditions.

9. Reliability and performance checklist

  • Pin and record the wkhtmltoimage version.
  • Log the full command, URL, output dimensions, stderr, and exit status.
  • Use an explicit viewport width for reproducible responsive behavior.
  • Prefer deterministic page readiness over a large arbitrary delay.
  • Keep capture pages free of unnecessary third-party scripts and widgets.
  • Use a bounded timeout in the surrounding job runner.
  • Retry transient network failures, but do not blindly retry a deterministic CSS failure.
  • Compare output dimensions in CI so a bar-only regression is detected early.

Large widths, long delays, complex JavaScript, and full-page images increase CPU, memory, and wall-clock time. Capture a dedicated export route when the production page contains animations or interactive state.

10. Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server. One request returns a PNG, JPEG, WebP, or PDF, with options for full-page capture, lazy images, custom viewport and device presets, waiting for selectors or network idle, custom CSS and JavaScript, hidden selectors, resource blocking, headers, cookies, user agents, timezone, geolocation, and caching. The API parameter names used by other screenshot services also work.

Consent banners, popups, and chat widgets can be removed before capture.
Consent banners, popups, and chat widgets can be removed before capture.

See the ScreenshotNeo API documentation for the complete option list.

cURL

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

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.test/page"},
    timeout=90,
)
r.raise_for_status()
open("page.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.test/page'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const body = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('page.webp', body);

Before capture, ScreenshotNeo accepts the cookie or consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response reports the result with X-Page-Verdict and X-Billed headers. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.

The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan. Create a free ScreenshotNeo account.

FAQ

Will increasing --height always fix a bar?

No. It helps when the output viewport is genuinely too short. CSS clipping, responsive breakpoints, JavaScript timing, and lazy loading can still produce a bar.

Should I use --window-status instead of a delay?

Only when the page reliably sets the expected status and your binary handles it correctly. Historical issues show version-specific behavior, so verify it with your exact build.

How do I prove whether wkhtmltoimage or the page is responsible?

Capture a tall minimal local HTML file with the same binary. A normal local result points toward the target page’s layout, scripts, or resources.

Can a screenshot service capture a full page without maintaining wkhtmltoimage?

Yes. ScreenshotNeo accepts a URL and supports full-page capture, waits, viewport controls, and page cleanup through one API request.