A Field Guide to Debugging Blank and Broken Screenshots

A screenshot comes back blank, or half-loaded, or visibly different from what a browser shows a human visitor. Before assuming something is broken on the API side, it's worth working through a short checklist — the overwhelming majority of these cases trace back to one of a handful of well-understood causes, most of which are already covered by a parameter you're not yet using.

1. The Page Wasn't Done Rendering Yet

The single most common cause of a blank or partial capture: the screenshot fired before the page finished loading its real content. Lazy-loaded images, skeleton loaders, and entrance animations all look "blank" or "wrong" if captured mid-transition.

Fix: add a delay, or switch to waitForDom on v3/analyze for pages with a slower initial data fetch. See Waiting for Lazy-Loaded Images and Animations for the full breakdown of when to reach for which.

2. A Consent Banner or Overlay Is Covering the Page

A cookie banner, a promo modal, or an onboarding tour can render on top of everything else, making a technically-successful capture look "wrong" even though the page loaded fine underneath.

Fix: hideCookie handles the common consent-banner case automatically. For anything else, hide with a CSS selector removes a specific overlay before capture. See Why Cookie Consent Banners Break Screenshot Automation and A Recipe for Clean Onboarding Tour Screenshots.

3. The URL Redirected Somewhere Unexpected

If the target URL redirects — to a login page, a locale-specific subdomain, or an error page — the capture is technically accurate, just not of the page you meant to capture. This is especially common with authenticated app URLs that silently bounce to a login screen when the session isn't valid.

Fix: confirm the exact URL resolves to the intended page when opened directly in a normal browser, logged in with the same session the request assumes. If the destination requires authentication, the practical pattern is pointing the request at a URL that's already session-valid — see How to Screenshot a Login-Protected SaaS App for that pattern.

4. The Page Itself Errored for Everyone, Not Just the Capture

Sometimes the page really is broken — a client-side JavaScript error crashed the render, a backend dependency timed out, or a feature flag put the page into an unexpected state. A screenshot of a genuinely broken page is not a capture bug; it's the capture doing its job and reporting bad news.

Fix: open the same URL in an ordinary browser at the same time. If it's broken there too, the fix belongs to whatever's actually serving that page, not to the capture request.

5. Sticky or Fixed Elements Duplicated Down a Full-Page Capture

A full-page capture that shows a header or a chat widget repeated multiple times down the image is a rendering artifact of position: fixed or position: sticky elements during a stitched full-page screenshot, not a broken page.

Fix: hide the specific fixed element before capture, or accept the duplication as a known cosmetic side effect if the element isn't the point of the screenshot. See Why Sticky Headers Break Full-Page Screenshots for the full explanation.

6. Format-Specific Artifacts Are Being Mistaken for Bugs

A JPEG capture that looks slightly soft around text, or a PNG that's larger than expected, isn't a bug — it's the format's normal trade-off. See PNG vs JPEG vs WebP if a format choice is the actual source of confusion.

A Practical Debugging Order

When a capture looks wrong, work through these in order before assuming the API is at fault: open the URL in a real browser first, check for a redirect, check for an overlay, check for something on the page still loading, and only then consider format or full-page stitching artifacts. In practice, one of the first three explains almost every case.

If a capture still looks wrong after ruling all of this out, that's worth a real support conversation — but most "broken screenshot" reports resolve at step one or two, and Snapshot Site exposes every one of these fixes as a plain request parameter rather than something hidden away.