ScreenshotNeo

BlogHow-to

How to Fix Webshot Screenshots That Miss the Finished Page

Fix webshot captures that miss late content or stop at the viewport. Learn delay, clipping, selectors, webshot2 migration, and reliable alternatives.

By the ScreenshotNeo team30 September 20268 min read

How to Fix Webshot Screenshots That Miss the Finished Page

Webshot usually misses a “finished” page for one of two reasons: the page was captured before JavaScript and remote assets completed, or the capture was clipped to the viewport instead of including the whole document. Start by increasing delay, then check cliprect and selector. If you use the legacy R package, also check whether PhantomJS is the source of inconsistent rendering and consider webshot2, which uses Chromium.

This guide covers the R packages named webshot and webshot2. A browser extension called Webshot has different controls; that distinction is covered near the end.

1. Identify whether the problem is timing or cropping

Look at the output before changing code:

  • Blank cards, missing images, or content that appears later in a normal browser: the capture probably happened too soon.
  • The page looks correct until it abruptly ends at the browser window height: a viewport clip is probably enabled.
  • Only one component is missing or the wrong component is present: inspect the CSS selector and the selector behavior of your installed package.
  • Layout, fonts, or scripts differ substantially from a current browser: the legacy PhantomJS runtime may be responsible.

Save the exact package version, URL, function call, and output image while troubleshooting. A screenshot without the call that produced it is difficult to diagnose.

2. Wait longer with delay

Both package APIs expose delay, the amount of time to wait before taking the screenshot. The webshot reference specifically recommends a longer delay when assets need time to display; its example uses half a second. That value is an example, not a universal readiness threshold. JavaScript work, remote images, fonts, animations, and the target server can all change the required wait.

A fixed delay gives late-loading page assets time to appear before capture.
A fixed delay gives late-loading page assets time to appear before capture.

Legacy webshot

webshot::webshot(
  "https://example.com",
  "page.png",
  delay = 2
)

webshot2

webshot2::webshot(
  "https://example.com",
  "page.png",
  delay = 2
)

Increase the value incrementally and compare the files. For example, try 0.5, 1, 2, and 5 seconds when the page is known to be slow. A fixed delay is only a pause; it does not prove that the application reached a semantic “finished” state. A page can continue loading after the timer, and a page can be visually complete before it expires.

Make the test reproducible

  1. Use the same URL and output format for every attempt.
  2. Record the delay used beside each output file.
  3. Disable animations or hide known loading placeholders with page CSS when they interfere with comparison.
  4. Use a stable test URL if the page changes on every request.

3. Remove viewport clipping when you need the full page

The legacy repository documents a default virtual viewport of 992×744 pixels. Its default screenshot includes the page beyond that viewport, but an explicit cliprect = "viewport" limits the result to the visible window. webshot2 likewise documents that, when neither cliprect nor selector is supplied, the clip includes the whole page.

Viewport clipping and full-page capture produce different boundaries even when rendering is correct.
Viewport clipping and full-page capture produce different boundaries even when rendering is correct.

Full-page capture

webshot::webshot(
  "https://example.com",
  "page.png",
  delay = 2
)

Remove cliprect = "viewport" if it appears in your call. Do not add a viewport clip merely to control image size; use a deliberate viewport and resize step when your workflow requires fixed dimensions.

Intentional viewport capture

webshot::webshot(
  "https://example.com",
  "viewport.png",
  cliprect = "viewport",
  delay = 2
)

This is appropriate for a hero fold, a visual regression region, or a thumbnail. It is not a full-document capture.

4. Use selectors only when you intend to crop

A selector changes the capture region from the page to a DOM element. Check the installed package before assuming how multiple matches behave:

  • Legacy webshot uses the first matching element.
  • webshot2 documents capture of all matching elements.
webshot::webshot(
  "https://example.com",
  "content.png",
  selector = "#main-content",
  delay = 2
)

If a selector returns an empty or unexpected image, inspect the page source and confirm that the element exists after JavaScript runs. A class may be duplicated, renamed by a framework, or rendered only after an interaction. Remove selector temporarily to determine whether the page itself is correct.

5. Decide whether to migrate from webshot to webshot2

The official legacy repository says that webshot uses PhantomJS, whose development stopped in 2018, and recommends webshot2, which uses Chromium. This matters when a modern site depends on browser behavior that PhantomJS does not reproduce.

Question Stay on webshot Try webshot2
Does the page only need a small extra wait? Yes; test delay first. Optional.
Does the page use modern JavaScript, layout, or fonts? Possible compatibility risk. Preferred starting point because it uses Chromium.
Do you depend on selector matching? Remember the first-match behavior. Review the documented all-matches behavior.
Is the output clipped? Inspect cliprect. Inspect both cliprect and selector.

Migration does not remove the need to diagnose timing. webshot2 also supports delay, and the documentation gives the same reason for increasing it when assets need time to appear.

6. A complete diagnostic workflow

  1. Confirm the package. Check whether your script calls webshot::webshot or webshot2::webshot, and record the installed version.
  2. Capture without cropping. Remove cliprect and selector.
  3. Add a short delay. Start with an illustrative value such as delay = 2.
  4. Increase the delay. Compare several values and keep the smallest one that reliably includes the required content.
  5. Check the page in a normal browser. Verify that the missing content eventually appears and note whether it requires scrolling, clicking, consent, or authentication.
  6. Test the selector separately. Restore selector only after full-page output is correct.
  7. Try webshot2 for compatibility issues. PhantomJS-specific differences can look like a timing problem.
  8. Record a bug report. Include the URL, package and version, complete call, runtime, expected result, actual image, and whether the symptom is blank content or cropping.

7. Common errors and fixes

Symptom Likely cause Fix
Images or cards are blank Capture occurred before assets finished loading Increase delay gradually; verify the URL loads the assets in the capture runtime.
Only the visible browser area is present cliprect = "viewport" Remove the viewport clip for a full-page capture.
Only one matching component is captured Legacy webshot selector behavior Use a more specific selector or migrate to webshot2 after checking its documented all-match behavior.
The selected region is empty Element is rendered later or selector is wrong Increase delay, inspect the final DOM, and test without selector.
Modern layout differs from the browser PhantomJS compatibility limitations Try Chromium-based webshot2.
Longer delays never fix the output Problem is clipping, a failed resource, authentication, interaction, or runtime compatibility Classify the symptom, remove clipping, verify access, and test webshot2.
Results vary between runs Remote resources, animations, changing data, or a delay close to the page’s load time Use a larger safety margin, stabilize the page, and capture reproducibility details.

8. Reliability and performance considerations

Fixed waits trade reliability for latency

A longer delay can reduce early captures, but every request also takes longer. Use the shortest delay that consistently includes the required content, and keep separate values for fast static pages and slower application pages. Do not treat one successful run as proof that the value works for every URL.

Full pages cost more time and memory

A tall document requires more rendering and produces a larger image than a viewport clip or a single element. Capture only the region you need when the requirement is a component thumbnail or visual test. Use full-page output for documentation and archival captures.

Separate rendering from page readiness

The package documentation supports a time delay, not a universal network-idle or application-ready event. If a page needs a click, login, consent action, or infinite-scroll step before content exists, a larger delay alone may never produce the intended result.

9. Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. Its capture options include full-page screenshots with lazy images loaded, element capture by CSS selector, custom waits, dark mode, device presets, arbitrary viewports, retina scale, custom CSS and JavaScript, clicks, hidden selectors, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, async jobs, bulk capture, a usage API, and PDF controls.

The direct call is:

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

See the ScreenshotNeo API documentation for the complete parameter list. Python:

import requests

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

Node.js:

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
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('shot.webp', body);

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response reports the result with X-Page-Verdict and X-Billed headers. An MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account and use the API or MCP server when you do not want to maintain browser setup.

10. If you mean the Webshot browser extension

The extension uses different terminology from the R packages. Its Entire Page mode scrolls through the full page, captures each screen, and stitches the images into one tall result. Its Delayed Screenshot tool counts down before capturing the visible area. Do not apply the R package’s delay or cliprect advice to extension controls without checking which mode you selected.

FAQ

Does increasing delay guarantee that a page is finished?

No. It adds a fixed pause. A page can still be waiting on an interaction, authentication, or a failed resource.

Why does my output stop at 992×744?

That is the documented legacy webshot virtual viewport. Check for cliprect = "viewport"; remove it when you need the whole document.

Should every project move to webshot2?

Check compatibility first, but webshot2 is the recommended direction in the legacy repository because it uses Chromium while PhantomJS development stopped in 2018.

Can a selector capture several elements?

Behavior differs: legacy webshot uses the first matching element, while webshot2 documents all matching elements. Confirm the package in your script.

What should I include when reporting a failure?

Include the URL, package and version, full call, runtime, expected and actual output, and whether the issue is missing content or cropping.