URL2PNG Timeout Errors on Slow Websites: How to Fix Them
Diagnose whether a URL2PNG timeout comes from the target site or the capture service, then choose documented timing options without assuming they extend a timeout.
Start by measuring the target website and identifying which resource is slow. URL2PNG documents a fixed post-readiness delay and an element-based readiness marker, but its available Quickstart Guide does not publish a timeout threshold, timeout-specific error code, retry policy, or guaranteed timeout fix. Treat its timing options as controls for when capture happens, not as a way to extend a service timeout.
This guide shows how to isolate the cause, use URL2PNG’s documented capture options carefully, and decide when to escalate. It also gives a browser-independent alternative if you need to capture pages without managing a browser setup.
1. Classify the failure before changing settings
First establish whether the target site is slow, the screenshot request is failing, or the screenshot succeeds but captures the page before its important content appears. These are different problems and call for different fixes.
- Record the exact target URL, the time of the attempt, and the complete error text or response status and body.
- Repeat the same capture and note whether the failure is consistent or intermittent. Do not label an error with an undocumented URL2PNG error code.
- Open the target URL directly in a browser and compare how long it takes to load and render the content you expect.
- Check whether the returned screenshot is missing content even when the API request succeeds. That may be a readiness issue rather than a timeout.
If the page itself is slow, investigate its network requests. If the target is consistently fast but URL2PNG requests still fail, preserve the response evidence and contact URL2PNG support or consult its status resources.
2. Measure the target site and find the slow dependency
Use the browser’s Developer Tools Network panel to reload the page with request timing visible. Compare repeat runs, and if the site serves users in several regions, consider testing from more than one geography. Useful timing stages include DNS lookup, TCP connection, TLS handshake, time to first byte, and total request time. Cloudflare’s [slow website troubleshooting guide](https://github.com/cloudflare/cloudflare-docs/blob/production/src/content/docs/speed/troubleshooting/slow-website.mdx) describes these stages and common sources of delay.
Inspect the requests that hold up the page
- Slow origin response: If the document or API responses have a long time to first byte, investigate the application, server, database, and caching behavior.
- Large images or video: Check transfer sizes and whether media requests finish late. Make sure the page does not require an unnecessarily large asset before its useful content can render.
- Third-party scripts: Advertising, analytics, chat, and other external scripts can add requests or delay page work. Identify the specific dependency before deciding whether it can be deferred or removed.
- Render-blocking resources: Check stylesheets and scripts that delay the content the screenshot needs to show.
- Static asset cache misses: If repeat visits repeatedly fetch static assets from origin, investigate why caching is bypassed or missed. Do not indiscriminately cache personalized HTML or API responses.
A slow page can cause a capture to be incomplete or fail, but the available URL2PNG documentation does not say which target-site conditions trigger a service timeout.
3. Use URL2PNG’s documented timing controls
URL2PNG’s [Quickstart Guide](https://www.url2png.com/docs) documents two relevant readiness options. Choose one only when it matches the page’s behavior.
| Option | Documented behavior | Use when | Limit |
|---|---|---|---|
delay |
Adds a fixed wait after document readiness and asset loading. The guide shows delay=2. |
The page needs a brief, predictable wait after normal readiness, for example for an animation. | This is not documented as extending a URL2PNG service timeout. The guide consulted does not state a maximum value or promise that it resolves timeouts. |
say_cheese=true |
Waits until the page contains <div id='url2png-cheese'></div>. |
You control the page and can provide a marker when the screenshot-ready content exists. | The target must provide the marker. Do not expect this to work on a third-party site you cannot modify; the docs do not say it bypasses a timeout. |
These options affect capture timing. If you change a signed request’s query parameters, URL2PNG’s guide says the token is derived from the full query string plus the secret, so regenerate the token for the modified request.
Delay example
The URL2PNG guide’s v6 request uses an API key, a token, and a URL-encoded target URL. The token is an MD5 hash of the full query string plus the secret. The following illustrates the documented delay parameter; generate the token using the exact query and secret as URL2PNG requires rather than copying a placeholder token.
https://api.url2png.com/v6/PUBLIC_KEY/TOKEN/png/?url=https%3A%2F%2Fexample.com&delay=2Replace PUBLIC_KEY and TOKEN with the values generated for your account and request. This example demonstrates the parameter, not a timeout remedy.
Readiness-marker example
If you control the target page, add the marker only after the content needed for the image is ready:
<div id="url2png-cheese"></div>Then use the documented option in the capture request:
https://api.url2png.com/v6/PUBLIC_KEY/TOKEN/png/?url=https%3A%2F%2Fexample.com&say_cheese=trueAs with delay, changing the query means the signed token must match the full updated query string.
4. Reduce capture work when the image permits it
URL2PNG captures the viewport by default. Its fullpage=true option requests the entire document canvas. If the use case only needs the visible viewport, avoid requesting a full-page image; reducing capture scope may reduce the work requested, but URL2PNG does not promise this will resolve a timeout.
The guide documents viewport dimensions with a maximum of 5000×5000 and a default of 1480×1037. Use the smallest dimensions that preserve the content you need. A smaller viewport is not a documented timeout fix either.
fullpage=true: capture the whole document canvas; default behavior is viewport-only.viewport=WIDTHxHEIGHT: set the viewport dimensions within the documented maximum.unique: vary the request to force a fresh screenshot.ttl: set screenshot cache lifetime; the documented default is 2,592,000 seconds (30 days).
unique and ttl affect cache freshness, not the documented rendering timeout. A cache hit may help avoid a new render when the cached result is acceptable, but neither option changes a published URL2PNG timeout limit.
5. Troubleshoot common symptoms
| Symptom | Likely area to investigate | Next step |
|---|---|---|
| The target is slow in a normal browser too | Origin, network, or a slow page dependency | Use the Network panel to identify slow document, API, media, and third-party requests; fix the site or dependency that is delaying the page. |
| The capture returns, but JavaScript content is absent | Capture happened before the needed content was ready | If you control the page, try say_cheese=true with the documented marker. Otherwise, a short delay may help if the content appears predictably after normal readiness. |
A timeout-like failure persists after adding delay |
The delay may not address the failure; the service’s timeout behavior is not documented in the guide | Remove speculative changes, capture the exact response and timestamp, and escalate to URL2PNG with a reproducible request. |
| A signed request stops working after changing options | The token no longer matches the query string | Recompute the token using the updated full query and secret, following the URL2PNG guide. |
| Only full-page captures fail or take longer | The requested document canvas is larger than the viewport capture | Try viewport-only capture if it satisfies the task. Treat this as a diagnostic comparison, not a guaranteed timeout fix. |
| The target is fast but failures are intermittent | Could be target-side variability or a URL2PNG-side issue; the available docs do not define the error taxonomy | Compare multiple attempts and retain the exact request, timestamp, status, and response body for support. |
Cloudflare Browser Run has its own navigation wait settings and timeout limits. Its FAQ describes domcontentloaded, network-idle waits, selector waits, and a timeout increase up to 60 seconds for that product. Those settings and limits apply to Cloudflare Browser Run only; they do not establish URL2PNG behavior. See the [Cloudflare Browser Run FAQ](https://github.com/cloudflare/cloudflare-docs/blob/production/src/content/docs/browser-run/faq.mdx).
6. Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers. A GET request can return a PNG, JPEG, WebP, or PDF. Its capture options include wait-for-selector, delay, network-idle waiting, full-page capture, element capture, and controls for headers, cookies, user agent, and resource blocking. See the [ScreenshotNeo documentation](https://screenshotneo.com/docs/) for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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}`);ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools 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 screenshots.
Sign up free for 1,000 screenshots a month, with no card required.
7. Escalate with a reproducible report
If the target is consistently fast and URL2PNG still fails, gather evidence before contacting support:
- Exact target URL and the time of each attempt, including timezone.
- The generated capture URL with API credentials and secret-derived token removed.
- Response status, error text, and response body, if present.
- Whether direct browser loads are also slow, plus relevant Network panel timings.
- Whether the failure changes between viewport and full-page captures or after a documented readiness option.
The URL2PNG documentation links to a status page, but this guide does not establish any current incident or support response. Report observations rather than assuming a cause.
Performance, reliability, and cost considerations
Measure before adding waits: an unnecessary fixed delay adds latency to each capture, while an element marker can avoid guessing when a page you control is ready. Full-page capture can require more work than viewport capture. Repeatedly forcing fresh requests with unique changes cache behavior, while ttl controls how long URL2PNG retains screenshots; these settings concern freshness and caching, not timeout limits.
No timeout frequency, success rate, service threshold, or retry policy is established by the researched URL2PNG documentation. Do not build reliability assumptions around an invented limit or retry schedule. If adding your own retries, use a bounded policy appropriate to your application and avoid retrying indefinitely; the available source does not prescribe a URL2PNG retry policy. Cost depends on your URL2PNG account and plan; consult its current account documentation for pricing rather than relying on an assumed per-capture rate.
FAQ
Does URL2PNG publish its screenshot timeout limit?
The available Quickstart Guide does not state a timeout threshold or timeout-specific error code.
Does delay=2 give URL2PNG more time before timing out?
The guide describes delay as an added wait after document readiness and asset loading. It does not describe it as increasing a service timeout.
Can I use say_cheese=true on a website I do not control?
Only if that page already contains the required url2png-cheese element. The option depends on the marker existing in the target page.
Should I copy Cloudflare’s timeout setting into URL2PNG?
No. Cloudflare Browser Run documents settings for its own service; they are not evidence of URL2PNG parameters or limits.
What should I send support?
Provide a reproducible request with credentials removed, target URL, timestamp, response status and body, and measurements showing whether the target itself is slow.
