A Puppeteer screenshot that comes out blank, white or half-finished was almost always taken too early: before the content arrived, before an animation ended, or before a font loaded. The fix is to wait for the right thing, not for longer. This script waits for each of them:
The ready selector is the important argument: pick an element that only exists once the page has rendered what you want to see, such as the heading inside a dashboard or the first row of a results table.
Each cause below was reproduced on a test page and measured with Puppeteer 25.18 in headless Chrome.
1. The content arrives after the page loads
A dashboard, a single-page app or any page that fetches its data with JavaScript fires the load event long before there is anything to see. Puppeteer's goto waits for one of four events, and on a test page whose content arrives 1.5 seconds after load, they captured this:
| What the screenshot waited for | Content in the screenshot | Time taken |
|---|---|---|
domcontentloaded | No, blank | 0.1 s |
load | No, blank | 0.4 s |
networkidle2 | No, blank | 1.1 s |
networkidle0 | Yes | 3.1 s |
load, then waitForSelector | Yes | 1.6 s |
networkidle2 is the surprise. It fires once no more than two requests have been open for half a second, so the one request carrying the page's data is allowed to still be in flight. networkidle0 waits for every request, which worked here but took twice as long as waiting for the element, and it never fires at all on a page that keeps a connection open, such as a chat widget or a live feed: on such a test page it timed out. waitForSelector waits for exactly the thing you need and nothing else.
2. A fade-in animation has not finished
Pages often fade or slide their content in after load. Until the animation ends, the content is transparent or off-screen, so a screenshot shows the empty background. A test page whose hero fades in over three seconds was still blank in a screenshot taken after networkidle0, because the network was quiet long before the animation finished.
The style tag in the script sets every animation and transition to zero duration, so each jumps straight to its end state. With it, the hero was fully visible in the screenshot. It works for CSS animations; content animated by a JavaScript library has to be waited for with a selector or a short pause instead.
3. The web font is still downloading
A heading set in a web font with font-display: block is invisible until the font arrives. On a test page whose font took two seconds, a screenshot after domcontentloaded had no heading at all. document.fonts.ready resolves once the fonts the page is using have loaded. In that test the load event happened to wait for the font as well, but a font requested by content that appears after load is not covered by it, which is why the script checks fonts after the ready selector.
4. A cookie banner or overlay covers the page
This one gets worse the longer you wait. On a test page whose consent banner appears 300 milliseconds after load, a screenshot at load was clean and one at networkidle0 had the banner across the bottom. Waiting for the content gives overlays time to arrive too.
The third argument to the script takes a comma-separated list of selectors and hides them with display: none !important, which overrides the inline styles that banners usually set. With it, the banner was gone from the screenshot. Find the selectors once in the browser's developer tools; they rarely change.
5. Lazy-loaded images in a full-page screenshot
If the page is fine but a full-page screenshot has empty boxes where images should be, the images were never requested: they load when scrolled into view, and a full-page screenshot does not scroll. That needs a scroll before the capture, covered in Puppeteer full-page screenshots.
Not blank: blocked
Sometimes the screenshot is not empty but shows a "checking your browser" page or an access-denied message. Headless Chrome identifies itself: the user agent Puppeteer sent in these tests contained HeadlessChrome, and many sites challenge or refuse automated browsers. That is the site's decision to make. Check the screenshot, or the page title, before treating the capture as the site's real content, and if you need the site's data regularly, look for an official API or feed.
Without managing the browser
The domscout screenshot API takes the same waits as request fields, and flags a challenge page in the response so your code can tell it from the real thing:
If the selector never appears, the request is refused with 400 WAIT_FOR_SELECTOR_TIMEOUT instead of returning a blank image. hideSelectors takes up to 50 selectors. When you do not know a site's banner selectors in advance, cleanup hides likely consent banners, chat widgets and pop-ups on its own, for 1 extra credit on the Pro plan and above. A plain capture like the one above costs 1 credit, and the free screenshot tool tries a page without an account.
Next steps
- Full-page screenshots with Puppeteer, including lazy-loaded images.
- Screenshot a website with Python, where Playwright has built-in options for animations and overlays.
- The screenshot API guide lists every capture option, the screenshot API overview the plans, and the API documentation every error code.