ScreenshotMachine Returns a Blank Screenshot: Causes and Fixes

A blank ScreenshotMachine screenshot is a symptom, not a diagnosis. First inspect the response header X-Screenshotmachine-Response and the image itself: an invalid or incomplete API call can return an error image with a readable message. If there is no documented error code and the image is genuinely empty, check the URL, rendering delay, viewport, and any selector or crop settings one at a time. ScreenshotMachine documents these controls in its API reference.

1. Check whether the image is an API error

Do not assume a white-looking output means the website rendered blank. ScreenshotMachine can return an image containing an error message. Read its text and inspect X-Screenshotmachine-Response before changing capture settings.

Header value	Meaning	What to check
missing_key	The customer key was not included.	Pass the required key parameter.
invalid_key	The supplied key is invalid.	Check that it is current and copied correctly.
missing_url	No target URL was supplied.	Pass the required url parameter.
invalid_url	The URL is invalid, or the target returned an authorization-required response.	Check URL encoding and whether the page requires authentication.
invalid_hash	The request hash did not match.	If a secret phrase is configured, calculate the hash for the exact URL and phrase.
no_credits	The account has no remaining credits.	Check account credits.
invalid_selector	The CSS selector is invalid.	Check selector syntax and whether it matches the page.
invalid_crop	The crop region is invalid.	Check the crop coordinates and dimensions.
system_error	A generic service error occurred.	Retry once, then save the response details for support.

Keep API keys and secret phrases private. If you share a diagnostic request, redact those values.

2. Reproduce the request with a known-good baseline

Keep the request simple before tuning options: provide a valid key and fully qualified URL, use a standard desktop viewport, and omit crop and selector parameters. This cURL example saves the returned body and headers separately so you can inspect both:

curl -sS -G 'https://api.screenshotmachine.com' \
  --data-urlencode 'key=YOUR_CUSTOMER_KEY' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'dimension=1366x768' \
  --data-urlencode 'device=desktop' \
  --data-urlencode 'format=png' \
  --data-urlencode 'delay=2000' \
  -D response-headers.txt \
  -o screenshot.png

# Inspect the documented diagnostic header:
grep -i '^X-Screenshotmachine-Response:' response-headers.txt

Replace the example URL with a page you are authorized to capture. The documented API requires key and url; the other parameters shown are useful baseline settings. If the output is an error image, the header and image message should point to request validation or account state.

3. If the request is valid, troubleshoot the page render

Give JavaScript and assets time to load

The documented delay default is 200 ms, and supported values run from 0 to 10,000 ms. For long pages containing images or animations, ScreenshotMachine suggests considering a delay of 2000 ms or more. Try a longer delay, such as delay=2000, then compare a fresh capture. A delay is a diagnostic adjustment, not a guarantee that every page will render.

Match the viewport and device

Device emulation and dimensions affect responsive layouts. The generator supports desktop, phone, and tablet device choices. Its documented width range is 100–1920 pixels; height is 100–9999 pixels or full. Try the device and dimensions where the page actually displays content. A layout may hide or rearrange content at a narrow width.

Remove restrictive selector and crop settings

A CSS selector capture returns the first matching DOM element; an invalid selector can produce invalid_selector. A crop rectangle can exclude the content or be rejected as invalid_crop. Remove both settings for the baseline capture, then add one back at a time. Confirm the selector exists on the page and that crop coordinates fall within the visible area.

Handle cookie dialogs and popups

A consent banner or modal can cover the page while leaving the screenshot technically valid. ScreenshotMachine supports a click selector to click an element before capture and a hide selector to hide matched elements. Check the selector against the target page. URL-encode reserved characters such as # when placing selectors in query parameters.

Check access and target behavior

If the target requires login, blocks automated access, redirects, or only displays content after an interaction, the captured page may not match what you see in a normal browser. The documentation identifies authorization-required responses as one possible reason for invalid_url. Compare the URL and access state, and determine whether the page needs a click or other supported setting. A valid image with no documented API error does not identify a universal root cause; the target page and request details matter.

4. Compare captures systematically

1. Save the original image, HTTP response headers, exact parameter names and values, and timestamp.
2. Make a baseline capture with a full URL, valid key, standard desktop dimensions, and no selector or crop.
3. Increase delay and capture again.
4. Change only the device or viewport and compare.
5. Reintroduce click, hide, selector, or crop options one at a time.

Changing one setting at a time makes it easier to see which setting affects the output. If the same URL works in a normal browser but remains blank in a valid capture, include that comparison when escalating.

5. Troubleshooting checklist

Symptom	Likely check	Fix
Image contains an error message	X-Screenshotmachine-Response	Follow the matching error row above; do not treat it as a page-rendering issue.
Only some requests fail	URL encoding, missing parameters, or changing target access requirements	Compare the encoded URL and request parameters with a working request.
Mostly white page, no error code	Render timing, target behavior, or responsive layout	Try a longer delay and the expected viewport; compare with a normal browser.
Header or banner appears, content is obscured	Consent overlay or popup	Use a valid click or hide selector.
Only a small or empty region appears	Selector or crop limits output	Remove those parameters, then validate and reapply them individually.
Capture shows an outdated page	Cached result	Review cacheLimit; set it to 0 while diagnosing to avoid using a cached image.

6. Reliability, performance, and cost notes

Longer delays can help pages with slow assets or animation, but they also add time to each capture. Use a modest delay for routine pages and increase it for pages where the comparison shows rendering is incomplete. Avoid diagnosing with cache enabled: ScreenshotMachine documents cacheLimit in days, with 0 disabling cache use; it also allows fractional day values for shorter intervals. Confirm the current account’s credit balance when the header reports no_credits. The supplied documentation does not state a universal cause or a guaranteed render time for a genuinely blank page.

7. Escalate with useful evidence

If the request still fails, contact ScreenshotMachine at info@screenshotmachine.com. Include the redacted request, HTTP status, X-Screenshotmachine-Response value, output image, target URL if shareable, and which single-setting comparisons you tried. Remove the customer key and secret phrase. The email is listed on its contact page.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. Its API can return an image or PDF from one GET request. 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}`);

• Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
• Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Responses identify the page verdict and billing status in headers.
• An MCP server provides take_screenshot, get_page_info, and capture_pdf 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; every feature is on every plan.

Sign up free for 1,000 screenshots a month, no card required.

FAQ

Does a blank image always mean ScreenshotMachine is down?

No. It can be an error image, a valid capture of a page with no visible content, or a page obscured by layout or overlays. Check the response header and image message first.

What delay should I start with?

Use the documented default for a quick baseline, then compare with 2000 ms for a page whose images or animation may need more time. The documentation allows delay values up to 10,000 ms.

Why does the page look correct in my browser but blank in the capture?

The browser and capture can differ in viewport, timing, access state, and interaction state. Compare those conditions and test one parameter at a time.

What should I send support?

Send the redacted request, response status, error header value, output image, target URL if shareable, and the settings you compared. Never include the API key or secret phrase.