Why Full-Page Screenshots Return a White Screen and How to Fix Them
A white full-page screenshot can come from readiness, geometry, rendering, browser, or transparency problems. Diagnose and fix each cause.

A white full-page screenshot does not identify one failure. The usual causes are an application that was captured before it was ready, incorrect full-page geometry, lazy-loaded content that never rendered, a browser renderer or protocol failure, or an intentionally transparent image displayed on a white background.
Start with a control capture: use a known viewport, log the final URL, assert that expected text exists, check the target element’s dimensions, and save a viewport screenshot. If the viewport is also white, fix navigation, authentication, JavaScript errors, or blocked resources before debugging fullPage.
1. Confirm the failure with a control capture
Run this Playwright script against a page you control. It records the final URL, checks visible content, reports document geometry, saves a viewport image, and then attempts the full-page image.
import { chromium } from 'playwright';
const browser = await chromium.launch();
const page = await browser.newPage({
viewport: { width: 1440, height: 900 },
deviceScaleFactor: 1
});
page.on('console', message => console.log(`[console:${message.type()}] ${message.text()}`));
page.on('pageerror', error => console.error('[pageerror]', error));
page.on('requestfailed', request => {
console.error('[requestfailed]', request.url(), request.failure()?.errorText);
});
await page.goto('https://example.com', { waitUntil: 'domcontentloaded', timeout: 60000 });
console.log('Final URL:', page.url());
await page.locator('body').waitFor({ state: 'visible', timeout: 30000 });
const heading = page.locator('h1').first();
console.log('Heading:', await heading.textContent().catch(() => null));
const diagnostics = await page.evaluate(() => {
const root = document.documentElement;
const body = document.body;
const rect = body?.getBoundingClientRect();
return {
readyState: document.readyState,
scrollWidth: root.scrollWidth,
scrollHeight: root.scrollHeight,
bodyWidth: rect?.width ?? 0,
bodyHeight: rect?.height ?? 0,
bodyBackground: getComputedStyle(body).backgroundColor
};
});
console.log(JSON.stringify(diagnostics, null, 2));
await page.screenshot({ path: 'viewport.png', type: 'png' });
await page.screenshot({ path: 'full-page.png', type: 'png', fullPage: true });
await browser.close();
Playwright defines fullPage: true as a screenshot of the full scrollable page rather than the visible viewport (Page API). Keep both files. Their difference tells you whether the problem is page-wide or specific to full-page measurement and stitching.
2. Make page readiness explicit
Navigation completion is not the same as application readiness. A client-rendered app may still be routing, hydrating, fetching data, loading fonts, or inserting images after domcontentloaded. Wait for a condition that means the content needed in the screenshot exists.
await page.goto('https://example.com/dashboard', {
waitUntil: 'domcontentloaded',
timeout: 60000
});
await page.locator('[data-test="dashboard-ready"]').waitFor({
state: 'visible',
timeout: 30000
});
await page.locator('h1').waitFor({ state: 'visible' });
await page.evaluate(() => document.fonts?.ready);
await page.screenshot({ path: 'dashboard-full.png', fullPage: true });
Use networkidle only when it matches the application’s behavior. Analytics, WebSockets, polling, and ads can keep a page busy indefinitely. A finite application signal, a selector, or a bounded delay after the signal is usually more deterministic than a large universal sleep.
Authentication and redirects
- Log
page.url()after navigation. A login page or consent route can be valid HTML but contain none of the expected content. - Load storage state or cookies before navigation when the page requires a session.
- Assert a distinctive heading, table, or root selector instead of assuming a successful HTTP response means the application rendered.
3. Check full-page geometry
A full-page capture depends on the document’s scrollable dimensions. Collapsed containers, a hidden application root, an iframe that has not attached, or a zero-sized body can produce a white or nearly empty image.
const geometry = await page.evaluate(() => {
const root = document.documentElement;
const body = document.body;
const app = document.querySelector('#app, #root, main');
const appRect = app?.getBoundingClientRect();
return {
document: {
scrollWidth: root.scrollWidth,
scrollHeight: root.scrollHeight,
clientWidth: root.clientWidth,
clientHeight: root.clientHeight
},
app: appRect ? {
x: appRect.x, y: appRect.y,
width: appRect.width, height: appRect.height
} : null,
bodyDisplay: body ? getComputedStyle(body).display : null,
bodyVisibility: body ? getComputedStyle(body).visibility : null
};
});
console.log(geometry);
Investigate a zero width or height before changing image encoding. Check CSS that sets display:none, visibility:hidden, a zero-height flex child, an overflow container, or a root that is replaced during hydration. If the content is inside an iframe, wait for the iframe element and its content before capturing.
4. Handle lazy-loaded content deliberately
Full-page capture is not an infinite-scroll loader. Many sites request images only when an element enters the viewport. Scroll through the page in bounded steps, wait for each batch, and stop when the height stabilizes or the application reports completion.
async function loadLazyContent(page, maxPasses = 20) {
let previousHeight = 0;
let stablePasses = 0;
for (let pass = 0; pass < maxPasses; pass++) {
const height = await page.evaluate(() => document.documentElement.scrollHeight);
const step = Math.max(400, Math.floor(window.innerHeight * 0.8));
for (let y = 0; y < height; y += step) {
await page.evaluate(scrollY => window.scrollTo(0, scrollY), y);
await page.waitForTimeout(150);
}
await page.evaluate(() => window.scrollTo(0, document.documentElement.scrollHeight));
await page.waitForTimeout(500);
const newHeight = await page.evaluate(() => document.documentElement.scrollHeight);
if (newHeight === previousHeight) stablePasses++;
else stablePasses = 0;
previousHeight = newHeight;
if (stablePasses >= 2) break;
}
await page.evaluate(() => window.scrollTo(0, 0));
}
await loadLazyContent(page);
await page.screenshot({ path: 'lazy-loaded-full.png', fullPage: true });
Use a maximum number of passes and a finite wait. Otherwise an infinite feed, polling component, or continuously growing ad slot can make the job run forever.
5. Use the full-page option only after the control works
In Playwright, the documented call is:
await page.screenshot({ path: 'page.png', fullPage: true });
Puppeteer exposes the equivalent option:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 });
await page.goto('https://example.com', {
waitUntil: 'domcontentloaded',
timeout: 60000
});
await page.waitForSelector('h1', { visible: true, timeout: 30000 });
await page.screenshot({ path: 'viewport.png', type: 'png' });
await page.screenshot({ path: 'full-page.png', type: 'png', fullPage: true });
await browser.close();
})();
Playwright also supports element targeting, masking, scale, and background controls. Use those when the page is healthy and the requirement is narrower than a full document.
| Option | Use | Failure to watch for |
|---|---|---|
viewport |
Set a known layout width and height before navigation. | Responsive breakpoints can hide or move the content you expect. |
deviceScaleFactor/scale |
Control pixel density and output size. | Large values increase memory and file size. |
fullPage |
Capture the full scrollable document. | It does not guarantee lazy content was loaded. |
clip or locator screenshots |
Capture a known region or element. | A detached or zero-sized element cannot be painted. |
omitBackground |
Produce transparent output. | A transparent PNG can look white in a viewer. |
type |
Choose PNG, JPEG, or WebP where supported. | JPEG has no alpha channel; transparency diagnostics require PNG. |
animations, masking, and custom CSS |
Reduce motion or hide unstable regions. | CSS that hides the root or content can make the capture blank. |
6. Rule out transparency and background mistakes
Playwright’s omitBackground hides the default white background and allows transparent screenshots (Page API). A PNG viewer may show transparent pixels against white, making a valid capture appear blank. Temporarily remove omitBackground, force PNG output, and inspect the alpha channel. Also check whether page CSS sets a white foreground on a transparent or white background.
await page.screenshot({
path: 'diagnostic.png',
type: 'png',
fullPage: true,
omitBackground: false
});
7. Debug the browser renderer and protocol
If the viewport is correct, geometry is positive, and readiness is proven, investigate the browser process. Run headed, inspect DevTools, and collect console, request, and browser logs. Puppeteer’s debugging guide recommends launching with headless: false; it also documents DevTools, dumpio, and protocol diagnostics (Puppeteer debugging).
const browser = await puppeteer.launch({
headless: false,
devtools: true,
dumpio: true
});
In Playwright, pause with the Inspector or run headed while watching the page. Check failed requests, JavaScript exceptions, browser crashes, sandbox or launch errors, and Playwright/Puppeteer-to-browser version mismatches. Chrome DevTools Rendering tools can show paint flashing and layout-shift activity while the page is still repainting (Rendering performance).
8. A deterministic repair recipe
- Set an explicit viewport and device scale.
- Navigate and log the final URL.
- Wait for the application’s ready selector and required fonts.
- Assert expected text and save a viewport PNG.
- Log document and target-element geometry.
- Scroll in bounded increments if content is lazy-loaded.
- Return to the intended scroll position.
- Capture with
fullPage: true. - Keep the viewport image beside the full-page image for comparison.
- If it remains white, run headed and inspect logs, network failures, transparency, and version boundaries.
9. Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Viewport and full-page images are both white | Redirect, authentication, JavaScript error, blocked resource, or hidden root. | Log final URL, assert expected text, inspect console and failed requests, and verify element dimensions. |
| Viewport works, full-page is white | Incorrect scroll geometry, collapsed content, or full-page renderer failure. | Print scroll dimensions, inspect the root bounding box, then run headed with protocol logs. |
| Only images are missing | Lazy loading never triggered or image requests failed. | Scroll in bounded steps, wait for image completion or an app signal, and inspect request failures. |
| Capture is white only in a particular viewer | Transparent PNG displayed on a white canvas. | Capture once with omitBackground: false and inspect alpha. |
| Capture hangs indefinitely | Network idle never occurs because of polling, sockets, or ads. | Use a selector or application-ready signal and enforce navigation, selector, and overall timeouts. |
| Headed mode also fails | Browser crash, sandbox issue, incompatible binary, or renderer/protocol failure. | Read browser stderr, enable DevTools/protocol logging, and align library and browser versions. |
| Output is huge or process memory spikes | Very tall page, high device scale, or large full-page bitmap. | Use scale 1, a bounded page, element or clipped captures, and a memory limit. |
10. Performance, reliability, and cost
- Performance: Full-page images require more layout, paint, memory, encoding, and transfer than viewport images. Keep the viewport and device scale as small as the use case permits, and avoid repeated full-page captures during polling.
- Reliability: Prefer application signals over arbitrary sleeps, cap lazy-loading passes, set navigation and selector timeouts, and retain diagnostic metadata such as final URL, dimensions, and verdicts.
- Reproducibility: Pin the browser automation library and browser binary, set timezone and locale where layout depends on them, and use a fixed viewport.
- Cost: Self-hosted browser work consumes compute and can require retries. Cache captures when the source has not changed, and avoid retrying a deterministic authentication or selector failure.
Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and every response reports its result in X-Page-Verdict and X-Billed headers.
See the ScreenshotNeo API documentation for the complete parameter list. The basic request is:
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}`);
Options for difficult pages
ScreenshotNeo supports full-page capture with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets and arbitrary viewports, retina scale, PDF paper size/margins/landscape/page ranges, HTML/CSS-to-image, custom CSS and JavaScript, pre-capture clicks, hidden selectors, waits for a selector or delay or network idle, blocked ads/trackers/requests/resource types, custom headers/cookies/user agents/Authorization, timezone and geolocation, transparent backgrounds, image resizing, chosen cache TTLs, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification.
An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients. Every feature is available on every plan. Pricing is Free: 1,000 shots/month with no card; Starter: $5 for 3,000; Growth: $15 for 15,000; Pro: $39 for 60,000; Scale: $99 for 250,000; Business: $249 for 1,000,000. Yearly billing gives two months free.
Start with 1,000 free screenshots a month—no card required.
FAQ
Does a successful screenshot call prove the page rendered?
No. Validate the final URL, expected text, geometry, and the pixels in a viewport control image.
Should I always wait for network idle?
No. Polling, WebSockets, and third-party requests can prevent it from settling. Prefer a finite application-ready condition.
Why does scrolling help?
Scrolling triggers lazy-loaded resources. It must be bounded and followed by an explicit readiness check.
Which format is best for diagnosing a white result?
Use PNG with the default background first. It preserves detail and makes transparency easier to inspect.
When should I capture an element instead of the full page?
Use an element or clipped capture when the requirement is a card, chart, or known region. It avoids unrelated page geometry and reduces resource use.
Can an API replace browser debugging?
An API removes browser setup for routine captures, but pages with authentication, application errors, or unusual rendering still benefit from the control-and-diagnostics workflow above.


