Recommended Free Tools
A blank Puppeteer screenshot is a symptom, not a diagnosis. First confirm that page.goto() reached the intended URL and that the expected content exists in the page. Then wait for the application’s actual ready condition and check the viewport and screenshot bounds. A fulfilled navigation promise alone does not prove that the desired page rendered.
1. Check the destination and navigation response
Log the URL after navigation and inspect the response returned by page.goto(). In headless shell mode, a valid HTTP error response such as 404 or 500 does not necessarily make goto() throw, so explicitly check the status. Navigation to about:blank or a same-document hash change can return null rather than a response. Puppeteer Page.goto() API
As an Amazon Associate I earn from qualifying purchases.
const response = await page.goto('https://example.com', {
waitUntil: 'domcontentloaded',
timeout: 30000,
});
console.log('URL:', page.url());
console.log('Status:', response?.status() ?? 'no navigation response');
if (!response) {
throw new Error('Navigation returned no response; verify the destination and navigation type.');
}
if (!response.ok()) {
throw new Error(`Navigation failed with HTTP ${response.status()}`);
}Use a real page URL in place of https://example.com. If your workflow intentionally navigates to about:blank or changes only a hash, a null response may be expected; check the URL and resulting DOM instead of treating null as a network failure.
2. Verify the expected page content before capturing
After navigation, check for an element that identifies the intended page or for an application-specific readiness condition. If that element is absent, a screenshot wait setting cannot fix the underlying issue: investigate the destination, redirects, failed requests, or application errors first.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
await page.waitForSelector('[data-page="dashboard"]', {
visible: true,
timeout: 15000,
});
const title = await page.title();
const url = page.url();
console.log({ title, url });
await page.screenshot({ path: 'page.png' });Replace the selector with one that appears only when the page you need is rendered. For a single-page app, the initial HTML can load before client-side hydration or a data request finishes, so a page-specific selector or condition is more meaningful than document navigation alone.
3. Wait for the condition that means your page is ready
Use a selector for visible content
For a page with a stable marker, wait for it to appear and be visible. This is often the clearest readiness signal because it checks the content you intend to capture.
Use a page condition for application state
When readiness is not represented by one element, use page.waitForFunction() to check an application flag or other observable state, for example:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
await page.waitForFunction(() => window.appReady === true, {
timeout: 15000,
});Use a condition your application actually sets; do not assume a generic global variable exists.
Use a specific response when data drives the render
If a particular API response triggers the content you need, wait for that response and then verify the rendered DOM. A response arriving is useful evidence, but it is not by itself proof that the UI has finished updating.
Use network idle selectively
Puppeteer’s screenshot walkthrough shows navigation with waitUntil: 'networkidle2' before capture. It is an example, not a universal guarantee of finished rendering. Analytics, polling, streaming, or other ongoing requests can prevent network idleness even when the useful content is ready. Puppeteer Screenshots guide · Puppeteer waiting guide
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
page.waitForNetworkIdle() can help when late-loading resources matter, but prefer the application’s actual readiness condition when network activity is continuous or unrelated.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems4. Check viewport, clipping, and screenshot bounds
Content can be present but outside the region being captured. Check the viewport and any clip, fullPage, captureBeyondViewport, and background options. These control the screenshot’s bounds and appearance; they cannot create content that did not render. Puppeteer ScreenshotOptions API
await page.setViewport({ width: 1365, height: 900 });
await page.screenshot({
path: 'page.png',
fullPage: true,
});For a targeted capture, confirm that the clip coordinates and dimensions overlap the content you expect. Compare a plain viewport screenshot with the clipped or full-page version to isolate a bounds problem.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
5. Handle iframes and lazy-loaded content
If the target is inside an iframe
Wait for the relevant frame to load, then check for the content within that frame before taking the screenshot. A selector query on the main page does not establish that an embedded frame is ready. Puppeteer exposes frame and element screenshot APIs in its Page API.
If content loads only after scrolling
Make the page trigger the lazy load—by scrolling the relevant area, for example—and verify that the expected content has appeared before capture. There is no single lazy-load sequence that works for every application, so use the page’s own content marker as the check.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →6. Compare headless and headful runs without assuming a universal bug
Try headful mode as a diagnostic. If it works there but not in headless mode, keep the destination and page state constant and change one factor at a time: execution mode, Puppeteer/browser version, readiness condition, then viewport and screenshot options. Also inspect browser console messages, page errors, and failed requests. A difference between modes helps narrow the cause, but does not by itself identify one.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
A Puppeteer GitHub issue opened on January 9, 2018 reported a blank screenshot in headless mode while headful mode worked, using Puppeteer 0.1.13 on Ubuntu 17.04 against one website. That report is historical and specific to its version, operating system, and site; it does not establish a general defect in current headless Puppeteer. Puppeteer issue #1755
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.7. Troubleshoot by symptom
| Symptom | Likely area to check | Next action |
|---|---|---|
goto() resolves, but the image is blank |
Navigation resolution is not proof of the intended page or rendered content. | Log page.url(), inspect the response when present, and wait for a page-specific element. |
| The URL is right but the page marker never appears | The app may still be loading, may have failed, or may render only after a separate event. | Inspect console errors and failed requests; wait for the app’s actual ready condition. |
| Content appears in the browser but not in the image | Viewport, clipping, full-page capture, or content outside the captured region. | Try a plain viewport capture, then verify the viewport and clip bounds. |
| Main page is ready but embedded content is missing | The iframe may not have loaded or may not contain the expected content yet. | Wait for the target frame and verify its content before capture. |
| Capture hangs while waiting for network idle | Ongoing analytics, polling, or streaming may keep the network active. | Wait for a visible selector, application condition, or specific response instead. |
| Headful works and headless does not | A mode-specific difference is possible, but the cause is not established by that observation alone. | Hold URL and page state constant; compare versions, readiness, errors, and capture bounds one variable at a time. |
Or skip the browser setup
If you need a screenshot without managing Puppeteer, ScreenshotNeo returns an image or PDF from one GET request. Its capture flow accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for AI agents.
cURL example (replace the URL and API key):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for options and response details. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo free.
Frequently Asked Questions
Does a successful Puppeteer screenshot call prove that the page loaded correctly?
No. Check the resulting URL and expected page content before treating the image as valid.
Can I use network idle as the only readiness check?
It may help, but it is not a universal definition of readiness; ongoing requests can keep a page from becoming idle.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
