Urlbox screenshot is blank: how to troubleshoot it

A completed Urlbox render does not prove the intended page content appeared. A target can return an error or challenge page that Urlbox successfully captures. Without the render ID, target URL, options, status, and image, the cause of a blank screenshot cannot be identified conclusively; use the evidence below to determine whether the page was empty, captured too early, blocked, or failed during rendering.

Start by saving the render status and output details, then inspect the image itself. Match the next step to what those show rather than changing several timing and retry options at once.

1. Inspect the render result and image

For an asynchronous render, check its status by render ID. Urlbox documents a human-readable reason for failed renders. A successful render includes output details such as the render URL and output size. See the Urlbox API documentation.
Open the returned image. Check whether it is truly empty, a mostly white page, a browser error, a CAPTCHA, an access-denied message, or a page that is still loading. A request can succeed from Urlbox’s point of view even if the captured target content is an error or block page.
Compare with the target in a regular browser. Confirm the exact URL, redirects, visible content, and whether the page needs login, geography, or extra loading time.
Record the request configuration. Include the requested format, viewport, JavaScript setting, wait options, timeout, selectors, and any retry settings. This makes it possible to compare the image with the request that produced it.

The image’s file size can provide a clue, but it is not a diagnosis by itself. A small output might mean a sparse page, a challenge, or an incomplete render. If a render failed, start with its reported reason instead of treating it as a successful blank capture.

2. Check whether capture happened before the page was ready

First identify what “ready” means for this particular page. A basic page may be ready when its DOM loads; a JavaScript application may display its main content later; another page may need a spinner to disappear. Choose a wait condition that corresponds to visible content.

Option	Use it when	What to check
`wait_until`	You need to select a browser navigation or network readiness condition.	Choose the documented condition that matches the page’s loading behavior.
`wait_for`	A known CSS selector appears when the required content is ready.	Use a selector tied to the content, not a generic element that appears before it.
`wait_for_state`	The selector must be visible, rather than merely attached to the DOM.	Require the state that corresponds to content a viewer can actually see.
`wait_to_leave`	A loading indicator or spinner should disappear before capture.	Target the actual loading indicator and decide how a persistent match should be handled.
`delay`	The selected readiness condition occurs before the page finishes a known later step.	Add a measured extra interval after the readiness condition; avoid increasing waits blindly.

Urlbox documents a default wait_timeout of 30,000 ms. If a wait_for selector is not found by then, the screenshot proceeds by default. Set fail_if_selector_missing=true if absence of that selector should make the render fail instead of producing an image that looks successful. Similarly, a persistent wait_to_leave selector proceeds by default; use fail_if_selector_present=true when a still-visible loading indicator means the capture is unusable. Confirm current option names and behavior in Urlbox’s render options.

Pay attention to the documented timing change: in the September 2026 changelog, Urlbox says domloaded and turbo capture as soon as the DOM is ready, without the former hidden network settle of up to five seconds. If the page needs more time after DOM readiness, add an appropriate delay or wait for a meaningful selector. See the Urlbox changelog.

3. Determine whether the target site is blocking the render

A target may detect automated browsers using signals such as IP reputation, browser fingerprinting, request rate, or geography. The output may show a 403 or 429 response, a CAPTCHA or interstitial, or an almost empty page even when the response is 200. A rendered challenge is evidence about what the target served, not proof that the capture service failed. Urlbox describes these cases in its guide to avoiding blocks.

For known unusable HTTP statuses: consider fail_on, fail_on_4xx, or fail_on_5xx so the render reports an error for response codes you have decided are invalid for your workflow.
For transient failures: retry_on supports status and engine conditions such as timeout or crash. retry_with can alter retry options, including documented stealth or proxy escalation settings. Check current plan availability before using advanced retry or proxy options.
For a soft block that returns 200: status rules cannot identify the page as a challenge. Detect a known challenge selector, or use a minimum output-size condition such as small_size with retries. Establish a size floor from this page’s expected output; the guide’s illustrative 50,000-byte example is not a universal threshold.

Urlbox describes exponential backoff and up to three total attempts by default for the relevant retry behavior. Retries can help with transient conditions but cannot guarantee access to a site that continues to block the request. Use only the escalation settings appropriate to your account and target.

4. Verify URL, JavaScript, viewport, and format settings

URL and redirects: confirm the full target URL, including path and query string, and check where it redirects. A login page or redirect destination can be validly captured but contain none of the expected content.
JavaScript: check that JavaScript is not disabled when the page needs it. Urlbox documents that disable_js=true also prevents full_page=true and many options that require code execution in the page context. This is a configuration check, not proof that JavaScript caused a particular blank image.
Viewport and selector: verify the viewport is suitable for the page and that any element selector matches the intended content. Responsive layouts may hide or rearrange elements at different viewport sizes.
Format and output: check that the requested format and resulting file are handled as expected by your downloader or image viewer. For asynchronous jobs, use the output details returned for that render.
Timeout: Urlbox documents a 30,000 ms default and a 5,000–100,000 ms range for the render timeout. A timeout points to a render that exceeded its limit; raising it can help only if the target needs more time and the render can complete within the supported range.

If a render is unusually slow or resource-heavy, consider whether it should be submitted as an asynchronous job. Urlbox’s CLI guidance says heavy renders are better queued. A longer timeout is not a general fix for a block page, wrong selector, or disabled JavaScript.

5. Follow the evidence: diagnostic table

What you observe	Likely branch	Next action
The expected content appears after a delay in a browser; the render succeeded.	Readiness or timing	Choose `wait_until`, a meaningful `wait_for`, or a short `delay`. Fail explicitly if required content never appears.
The image contains a CAPTCHA, verification prompt, or access-denied message.	Target-site block	Inspect response status and challenge content. Configure detection and retries where appropriate and supported.
The target response is a 403, 429, or another status your workflow cannot accept.	HTTP response or block	Configure the relevant `fail_on` rule. Consider retries only for conditions that may be transient.
The asynchronous job reports failure.	Render or request failure	Inspect the status details and human-readable reason, then address that reported condition.
The image is returned although the `wait_for` selector was not found.	Selector wait default	Use `fail_if_selector_missing=true` when missing content must invalidate the result.
JavaScript-driven content is missing.	Configuration or page behavior	Confirm JavaScript is enabled and wait for the content’s actual rendered state.
The image shows an error or challenge page but the request completed.	Target response was rendered	Inspect the page and response; a completed capture does not establish that the intended content loaded.

These are diagnostic branches, not conclusions about an unseen render. Compare the request options, target behavior, status, and image before changing settings.

6. Troubleshooting Urlbox CLI and asynchronous jobs

If you use the Urlbox CLI, its common-problems documentation recommends beginning with urlbox doctor to check installation, configuration, session, credentials, and network access. JSON output can provide the full error and a hint. See Common Problems and the CLI troubleshooting reference.

CLI cannot authenticate or connect: run the doctor command and inspect the specific configuration, credential, session, or network finding it reports.
Render times out: verify the target’s response time and render complexity. If appropriate, adjust the timeout within the documented range or queue the work asynchronously; neither guarantees that a slow or blocked target will succeed.
Job is still pending: poll or query using the render ID according to the API flow, then inspect the final status and output details rather than assuming the first response is the finished image.
Job failed with a reason: use that reason to choose the next check. Avoid treating a failed job as a blank image unless an image was actually returned.

7. A repeatable debugging checklist

Save the exact request parameters, target URL, render ID, and time of the attempt.
Read the final status and any failure reason or output details.
Open the image and classify what it contains: expected page, incomplete page, error, challenge, or genuinely sparse content.
Load the same URL in a regular browser and identify the event or visible condition that means the content is ready.
Check JavaScript, redirect destination, viewport, selector, format, timeout, and wait settings.
For a timing issue, add the narrowest matching wait condition; make missing required content fail explicitly.
For a suspected block, inspect response status and challenge content; add status, selector, or size-based detection as appropriate.
Change one relevant setting at a time and compare the resulting status and image.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. Its capture can accept cookie and consent banners like a visitor and remove 60+ known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Only clean shots are billed: bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. See the ScreenshotNeo site and 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}`);

Replace YOUR_API_KEY with your key and change the target URL. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.

Performance, reliability, and cost

Keep waits specific

Waiting for a meaningful selector or readiness condition avoids spending extra time on every capture. Fixed delays are simple but can be too short on a slow run and unnecessarily long on a fast one. A selector timeout also has documented proceed behavior unless configured to fail, so make the failure policy explicit when required content matters.

Use retries for transient conditions

Retries and backoff can absorb intermittent status or engine failures, but they increase elapsed time and can repeat a request to a site that is already blocking automation. Keep retry conditions narrow, inspect the final status, and verify which advanced options are available on your plan.

Control timeouts and asynchronous work

Urlbox’s documented render timeout default is 30 seconds, with a 5–100 second range. Raising it may let a slow, valid render finish, while asynchronous jobs are suitable for work that should be queued. Neither setting repairs an incorrect URL, a never-matching selector, a JavaScript-disabled page, or target-side denial.

Estimate cost from useful output

The research materials do not specify Urlbox pricing, so check your current account and plan for per-render costs and any charges associated with retries or asynchronous work. For any screenshot workflow, estimate volume using expected successful captures and retry behavior, and monitor failed or blocked outputs so that unusable images do not silently flow downstream.

FAQ

Does a successful Urlbox status mean the website loaded correctly?

No. The target can return an error or challenge page that is still rendered successfully. Inspect the actual image and target response.

Why did Urlbox return an image when my selector never appeared?

By default, Urlbox proceeds when a wait_for selector is missing after its timeout. Set fail_if_selector_missing=true if that condition should fail the render.

Should I always add a longer delay?

No. First identify whether the page needs DOM readiness, a particular selector, a loading indicator to disappear, or a fixed extra interval. A delay cannot resolve a target block or incorrect configuration.

Can an HTTP 200 response still be a block?

Yes. A challenge or interstitial can be served with status 200. Detect it from the page content or use a page-specific size condition; status rules alone will not identify every soft block.

Does disabling JavaScript make a page blank?

It can omit content that depends on scripts, but the render evidence is needed to establish the cause. Check whether disable_js is set and whether the target renders its content without JavaScript.