ScreenshotOne Screenshots Missing Images: How to Fix Them

If images are missing from a ScreenshotOne screenshot, first check whether capture starts before they load or before lazy loading is triggered. Then inspect full-page scrolling and resource-blocking rules for anything that excludes the image or a dependency. A successful screenshot response does not guarantee that every image request succeeded. The exact cause depends on the target URL and request parameters.

Use this sequence to narrow it down: compare the page in a regular browser, adjust the wait condition, trigger lazy-loaded images during full-page capture, remove overly broad blocking rules, and surface failures for specific required image resources.

1. Check whether capture waits for images

ScreenshotOne’s wait_until accepts load, domcontentloaded, networkidle0, and networkidle2; the default is load. If the page inserts images after that event, test a different wait condition or add a delay. For a page with a known image container, wait for that selector as well.

A selector wait confirms that an element is present in the DOM. It does not prove the element is visible, that its image has finished downloading, or that the image decoded successfully. Use a selector that identifies the relevant content and verify the result visually.

2. Trigger lazy-loaded images in full-page captures

Lazy-loaded images often do not request their files until they approach the viewport. ScreenshotOne’s full_page=true enables scrolling automatically unless you override it. If images are still absent, adjust full_page_scroll_delay or reduce full_page_scroll_by so each section has more opportunity to load.

The options reference documents a default scroll delay of 400 microseconds and notes that some sites need a larger value. The full-page guide suggests trying the by_sections algorithm and adding 5–10 seconds of delay for difficult pages. Treat these as starting points, not guaranteed settings; tune on the page that is failing.

3. Inspect resource blocking

Review block_resources, block_requests, and any URL patterns or other blockers in the request. ScreenshotOne can block images directly. A broad rule can also block a required image host or a supporting resource. Blocking stylesheets, scripts, XHR, or fetch may change layout or stop content from rendering, so remove or narrow a rule if the page depends on it.

When troubleshooting, temporarily remove all blocking options. If the images return, restore rules one at a time and narrow the rule that caused the change. See the [ScreenshotOne options reference](https://screenshotone.com/docs/options/) and [proxy bandwidth guidance](https://screenshotone.com/docs/guides/how-to-reduce-proxy-bandwidth/) for the documented controls and cautions.

4. Make failures for required images visible

By default, ScreenshotOne may return a screenshot even when a resource request fails. If a particular image or image host is essential, set fail_if_request_failed to a narrow wildcard pattern for that resource. A matching browser or network error, or an HTTP 4xx–5xx response, can then fail the screenshot request. Handle the resulting error in your integration.

ScreenshotOne does not retry these failures automatically. Your application can catch matched_failed_request and perform a bounded retry if that is appropriate for the resource and job. Avoid broad patterns that turn unrelated failed requests into capture failures.

5. Check selector and viewport capture settings

For a selector screenshot, selector_scroll_into_view defaults to true and may help trigger lazy content near the selected element. Confirm that the selector matches the intended element and that the element’s image is actually loaded before capture.

For full-page or element captures, check that capture_beyond_viewport and the viewport dimensions match the intended output. A capture restricted to the visible viewport may omit content lower on the page even when the page itself is functioning correctly.

6. Compare the target page and resource route

Open the page in a regular browser and check whether the same images appear. If an image is absent there too, the issue is likely in the page, its image URL, or access to that resource. If it appears in your browser but not in the capture, compare the request’s wait and blocking settings and consider whether the render environment reaches the image through a different network route. ScreenshotOne’s proxy guidance notes that resource needs vary by page and routes can behave differently.

Runnable request examples

Start with a minimal request, then add one relevant setting at a time. Replace YOUR_ACCESS_KEY and the example URL. Consult the [ScreenshotOne options reference](https://screenshotone.com/docs/options/) for exact parameter syntax and supported values.

cURL

curl -G 'https://api.screenshotone.com/take' \
  --data-urlencode 'access_key=YOUR_ACCESS_KEY' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'full_page=true' \
  --data-urlencode 'wait_until=networkidle2' \
  --data-urlencode 'full_page_scroll_delay=5000' \
  -o screenshot.png

This example sets a 5,000 microsecond scroll delay (5 milliseconds), consistent with the documented unit. For pages that need seconds of delay, use the value appropriate to the API’s documented unit and validate it against the page; do not assume a value copied from another unit is equivalent. The full-page guide’s 5–10 second suggestion is a separate starting point to test.

Python

import requests

params = {
    "access_key": "YOUR_ACCESS_KEY",
    "url": "https://example.com",
    "full_page": "true",
    "wait_until": "networkidle2",
}
response = requests.get(
    "https://api.screenshotone.com/take",
    params=params,
    timeout=90,
)
response.raise_for_status()
with open("screenshot.png", "wb") as image_file:
    image_file.write(response.content)

Node.js

const params = new URLSearchParams({
  access_key: 'YOUR_ACCESS_KEY',
  url: 'https://example.com',
  full_page: 'true',
  wait_until: 'networkidle2',
});

const response = await fetch(
  `https://api.screenshotone.com/take?${params}`,
  { signal: AbortSignal.timeout(90_000) },
);
if (!response.ok) {
  throw new Error(`ScreenshotOne request failed: ${response.status} ${await response.text()}`);
}
const image = Buffer.from(await response.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('screenshot.png', image));

For any language, inspect the HTTP status and response body on errors rather than saving an error response as an image. Keep access keys out of public client-side code and logs.

Options to tune and tradeoffs

Setting or check	When to use it	Tradeoff or limit
wait_until	Images are inserted or requested after an earlier page event.	Waiting for network idle may take longer or be unsuitable for pages with continuing network activity.
Delay or selector wait	The page needs extra time or has a known content container.	A selector proves DOM presence only; a delay is a fixed guess and can add needless time.
full_page and scroll controls	Images load as the page is scrolled.	More scrolling and delay can increase capture time; settings must match the page’s behavior.
by_sections	The default full-page behavior does not trigger all lazy content reliably.	Compare the actual output; the guide presents it as an option, not a universal fix.
block_resources / block_requests	You need to reduce unnecessary loads or investigate blockers.	Rules can suppress images or break supporting page resources.
fail_if_request_failed	A particular resource must load or the job should be treated as failed.	Matching failures become API errors; your integration owns bounded retry behavior.
selector_scroll_into_view	A selected element is outside the initial viewport and may lazy-load on scroll.	Scrolling the element into view does not establish that its image completed loading.
capture_beyond_viewport and viewport size	Element/full-page output is clipped or differs from the intended area.	Choose dimensions and capture scope that correspond to the desired result.

Common errors and fixes

Symptom	Likely cause	What to try
Screenshot succeeds but one or more images are absent	The image request failed, or the API returned a shot despite a resource failure.	Check the image URL and use a narrow fail_if_request_failed pattern for a required resource.
Only images below the fold are missing	Lazy loading was not triggered or scrolling moved too quickly.	Enable full-page scrolling; increase scroll delay or reduce scroll step; compare by_sections.
Images vanish after adding a blocker	A resource rule matches the image host or a dependency.	Remove blockers to confirm, then restore them one at a time with narrower patterns.
Selector capture is blank or incomplete	The selector exists before its image is visible or loaded, or capture scope is too small.	Check the selector, scroll it into view, wait for the page-specific condition, and review viewport and beyond-viewport settings.
Longer wait does not fix the image	The URL may be inaccessible, blocked, invalid, or failing independently of timing.	Open the page and image URL directly; inspect blockers and route-specific behavior.
Request fails with matched_failed_request	A resource matching fail_if_request_failed failed or returned 4xx–5xx.	Inspect the matching resource, correct its availability or pattern, and retry only under a bounded application policy.

Performance, reliability, and cost considerations

Longer waits and slower full-page scrolling give lazy content more time, but increase render latency. Start with the smallest wait and scroll adjustment that reproduces a successful capture. Waiting for network idle can be counterproductive on pages that keep connections active; a page-specific selector or measured delay may be more predictable.

For reliable pipelines, distinguish “the screenshot endpoint returned an image” from “all required images loaded.” Use targeted failure matching when completeness matters, log the target URL and relevant capture parameters safely, and retry transient failures only a limited number of times. A retry cannot fix a deterministic blocker or inaccessible image URL.

These settings trade capture time against completeness. The dossier does not establish a universal latency, success rate, or price for a particular configuration, so measure on representative target pages and check the provider’s current pricing separately.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. It accepts cookie and consent banners like a visitor and 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, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status.

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 request options. Its MCP server gives Claude, Cursor, and other MCP clients the tools take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.

FAQ

Does a successful ScreenshotOne response mean every image loaded?

No. A screenshot may be returned even if a resource failed. Use targeted failed-request handling when particular resources are required.

Will waiting for a selector guarantee its image is ready?

No. It establishes that the element is in the DOM, not that it is visible or that its image finished downloading and decoding.

Should I always use network idle?

No. It is one wait condition to test. Pages with ongoing network activity may make it a poor fit; compare it with a relevant selector or a page-specific delay.

What information is needed to identify the exact cause?

The target URL and the actual ScreenshotOne request parameters, including wait, scrolling, capture scope, and blocking rules. Without them, the cause cannot be determined conclusively.