Cloudinary Website Screenshot Returns a Blank Image: Causes and Fixes

A blank Cloudinary screenshot can mean two different things: the URL2PNG add-on returned an empty or failed capture, or a page’s Cloudinary image element never received its real src. Start by checking the actual network response. Record its HTTP status and inspect Cloudinary’s X-Cld-Error response header; that header often identifies transformation or delivery problems. If the response is a valid image but the page still looks blank, inspect the element’s src and data-src and check whether responsive-image JavaScript initialized.

This guide follows Cloudinary’s documented troubleshooting steps. It does not assume one universal cause: a blank result is a symptom, and the request, response, and DOM determine which fix applies.

1. Identify which blank-image problem you have

What appears blank	First place to investigate
The output from a URL2PNG screenshot URL	HTTP status, `X-Cld-Error`, add-on configuration and signing, then capture options and target-page rendering.
An image on a webpage using Cloudinary	The image request and the element’s `src` and `data-src`. A blank `src` can be temporary in a responsive-image workflow.
The screenshot image loads, but its captured page content is blank or incomplete	Separate image delivery from browser capture. Open the target URL directly, then investigate viewport, user agent, delay, and target-page rendering.

URL2PNG generates screenshots of public websites as a Cloudinary add-on. Its delivery URL has separate configuration and access requirements from ordinary image transformations. A successful screenshot request also does not guarantee that every target page will render its expected content.

2. Inspect the request and Cloudinary error

Open your browser’s Developer Tools and select the Network panel.
Reload the page or reproduce the screenshot request.
Select the Cloudinary request. Note the request URL and HTTP status.
Open the response headers and look for X-Cld-Error. Preserve the exact error text.
Check whether the response body is an image. If it is, inspect the element and page initialization separately.

Cloudinary recommends X-Cld-Error to diagnose transformation delivery problems. Do not infer the cause from the page’s blank appearance alone. A malformed transformation, access restriction, missing asset, uninitialized responsive image, or capture-rendering issue can look similar.

Read the evidence before changing the URL

Transformation or parameter error: correct the named value, syntax, ordering, or incompatible options.
Signature or authorization error: check add-on registration, URL signing or eager generation, and the asset’s delivery type.
Successful image response: inspect the bytes and the page’s DOM; this points away from a simple delivery failure.
No useful error header: retain the status, sanitized URL, response headers, and whether the target page opens directly.

3. Fix URL2PNG add-on access and signing

Cloudinary documents that URL2PNG must be registered and that, by default, delivery URLs using the add-on need to be signed or eagerly generated. The account can allow unsigned add-on transformations in its Console Security settings. That setting changes the access protection for these URLs; use it deliberately.

There are two documented routes:

Route	Use it when	Credential handling
Sign a dynamic delivery URL	The screenshot should be generated on demand.	Generate the signature on a backend with a Cloudinary SDK. Do not expose an API secret in browser-side code.
Eagerly generate the screenshot	The image should be generated ahead of its first view and then delivered.	Call Cloudinary’s authenticated API from a trusted backend, then use the generated delivery URL.

If an unsigned URL fails, verify the add-on registration and the account’s unsigned-transformation setting before changing unrelated transformation parameters. If you use private or authenticated assets, also check the delivery type and signature requirements: authenticated assets cannot be transformed on the fly, and eagerly generated derivatives require their own signatures.

4. Correct transformation and asset errors

A blank-looking result may be an invalid transformation response. Cloudinary documents common causes including invalid syntax or parameter values, conflicting options, unsupported features, missing base or overlay assets, and signature or access restrictions.

Read the exact X-Cld-Error message before editing the URL.
Check numeric values and transformation syntax. Cloudinary gives an invalid width as an example of a bad value.
Check whether the selected parameters can be combined. Cloudinary documents incompatible combinations, including certain uses of g_auto.
Check URL component ordering and confirm every referenced base, overlay, or other asset exists under the expected public ID and folder.
Confirm the resource type and delivery type match the asset.
If the asset is private or authenticated, apply the appropriate signature and delivery flow instead of treating it as a public asset.

Cloudinary documents that an invalid delivery URL returns a 400 Bad Request. A 400 is therefore a clue to inspect the URL and parameters, not evidence that the capture target itself is blank.

5. Check responsive Cloudinary images

Cloudinary’s responsive-image workflow can keep the intended image URL in data-src while the ordinary src is blank or a placeholder. In that case, the image may remain blank if the responsive library did not load or its responsive method was never called.

Inspect the image element in the Elements or Inspector panel.
Compare src with data-src. If src is empty while data-src contains a Cloudinary URL, check initialization before rewriting the transformation.
Confirm the intended responsive-image library loaded successfully and loaded before the code that invokes it.
Confirm the page calls the library’s responsive method at the appropriate point in its lifecycle.
Check that the image has a usable container width. A responsive method needs layout information to choose an appropriate image size.
Recheck the image request in Network after initialization. A populated data-src alone does not prove that the browser requested the image.

If both attributes are populated but the image request fails, return to the HTTP status and X-Cld-Error checks. If the request succeeds but the image element remains visually empty, inspect layout and page code as well as the response.

6. Diagnose a blank or incomplete URL2PNG capture

First open the public target URL directly and check whether it displays the expected page. Then compare that with the URL2PNG output. Cloudinary documents URL2PNG options including viewport, user agent, and delay; these are diagnostic levers for investigating a capture, not guaranteed fixes for any particular site.

Viewport: try a viewport that matches the page’s responsive layout. Content can differ across viewport widths.
User agent: check whether the target serves different page content for different user agents.
Delay: use a delay to investigate content that appears after the initial document load.
Direct-page comparison: compare the target page in a browser with the captured result to determine whether the problem is capture-specific.

If the target page is blank when opened directly, fix or investigate that page first. If it works directly but the capture is blank, retain the sanitized URL, status, response headers, and the options used. The reviewed Cloudinary documentation does not establish one universal fix for blank rendered content on third-party sites.

7. Troubleshooting checklist

Symptom or error	Likely area	Next action
HTTP 400 or invalid transformation message	URL syntax, parameter value, ordering, unsupported or conflicting options	Correct the specific issue named in `X-Cld-Error`; check numeric values and referenced assets.
Signature or authorization failure on URL2PNG	Add-on registration or protected delivery URL	Verify registration and sign the dynamic URL on a backend, or eagerly generate through the authenticated API.
Private or authenticated asset cannot be transformed dynamically	Authenticated delivery restrictions	Use the documented authenticated flow and ensure an eagerly generated derivative has its own signature.
`src` is empty and `data-src` has a URL	Responsive-image initialization	Check library loading, responsive-method invocation, and container width.
Image request succeeds but page element looks blank	DOM, layout, or image bytes	Inspect the response body and element dimensions; distinguish a valid image from an empty or hidden element.
Capture response is an image, but its page content is blank or incomplete	Target-page rendering or capture options	Open the target directly; compare viewport, user agent, and delay.
Referenced overlay or base asset is missing	Public ID, folder, resource type, or asset availability	Verify the asset exists and the transformation references the correct identifier.

8. Reliability, performance, and cost considerations

For a dynamic signed screenshot, generate the URL server-side and avoid putting signing secrets in the browser. Eager generation moves work ahead of the first view and gives you a generated delivery URL to use later. Choose between them based on when the screenshot needs to exist and where credentials can be kept securely.

When investigating latency or incomplete captures, change one capture option at a time and compare the result with the target page opened directly. A delay can help determine whether content appears after initial load, but it also adds waiting time. The source material does not provide a universal capture-time benchmark or guarantee for third-party page rendering.

Cloudinary’s add-on console lists plan allowances and prices, but these are vendor-listed figures and may change. Verify the current add-on plan in the console before budgeting. The troubleshooting sources do not establish a rate for blank captures or a universal billing outcome for failed requests.

9. Or skip the browser setup

For a screenshot endpoint you can call directly, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. Its API accepts the other screenshot APIs’ parameter names too, which can make switching simpler. See the ScreenshotNeo 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 and consent banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. The response identifies the page verdict and billing status in headers.
An MCP server gives AI agents, including Claude and Cursor, the take_screenshot, get_page_info, and capture_pdf tools.
1,000 screenshots a month are free with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan.

10. FAQ

Does a blank screenshot prove that Cloudinary URL2PNG is broken?

No. Check the response status and error header first, then distinguish a delivery failure from a blank target-page capture.

Should I expose a Cloudinary API secret to sign a screenshot URL in JavaScript?

No. Generate signed URLs on a trusted backend so the API secret stays out of browser code.

Can `data-src` contain the real image URL while `src` is blank?

Yes. That can be part of Cloudinary’s responsive-image workflow before its JavaScript initializes the real source.

What should I provide when asking for help?

Share the sanitized request URL, HTTP status, X-Cld-Error and other relevant response headers, whether the returned bytes are an image, and the element’s src and data-src. Remove signatures, tokens, and secrets.