If images disappear from a Puppeteer screenshot, first check whether request interception is aborting them. When interception is enabled, every request must be continued, answered, or aborted; an image-blocking rule can therefore cause the missing image itself. If interception is not the cause, record failed image URLs, confirm the image elements are ready, and only then investigate cache, service workers, or Chrome network restrictions.
1. Find out whether an image failed, is still loading, or is simply outside the screenshot
An empty area in a screenshot does not by itself prove that a request was blocked. The image may not have been requested yet, may still be loading, may have failed, or may have loaded outside the captured region. Start with one affected page and record the relevant image URL and browser error, if any.
As an Amazon Associate I earn from qualifying purchases.
Puppeteer’s page.evaluate() runs a function in the page context and returns its result. This inventory reports each document image’s URL and loading state:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →const images = await page.evaluate(() => [...document.images].map(image => ({
src: image.currentSrc || image.src,
complete: image.complete,
naturalWidth: image.naturalWidth,
})));
console.table(images);complete: truewithnaturalWidth: 0is a useful clue that the image did not load successfully.complete: falsemeans the image is not finished; it may need more time or page-specific lazy-loading behavior.- A successful image can still be absent from the screenshot if the capture region does not include it or the page has not triggered its lazy load.
To connect page state to network evidence, listen for request failures and inspect their URLs and error text. The Puppeteer network guide describes request monitoring and interception. Do not assume that every failed request is an image: identify its resource and URL before changing browser settings.
2. Check request interception before changing screenshot options
Search the code that creates the page and its helpers for setRequestInterception(true), request listeners, and calls to abort(), continue(), or respond(). Check all handlers, not just the screenshot function. Puppeteer’s guide demonstrates aborting image requests, and states that once interception is enabled, every request stalls unless it is continued, responded to, aborted, or completed from browser cache.
If interception is not needed, remove the handler or disable interception. If it is needed, make blocking rules narrow and resolve every request that should load. For example, this handler allows all requests, including images required by the screenshot:
await page.setRequestInterception(true);
page.on('request', request => {
if (request.isInterceptResolutionHandled()) return;
// Put a narrowly scoped blocking rule here only if necessary.
request.continue();
});If you do add a blocking condition, place it before continue() and abort only the resource types or URLs you intentionally want to block. With multiple listeners, follow Puppeteer’s guidance on checking whether interception has already been handled and on cooperative priorities; one handler can affect how another handler’s resolution is applied. See Request Interception and Page.setRequestInterception().
Free tools Windows power users keep installed
One-click scans. No signup required.
3. Wait for the images the screenshot actually needs
Puppeteer’s screenshot guide shows navigation with waitUntil: 'networkidle2' before calling page.screenshot(). Network idleness is useful as a lifecycle signal, but it does not establish that each target image loaded successfully. For reliable output, wait for the specific images or for an application-ready condition that represents the content you need.
For a page where all document images should be requested and completed, a bounded wait can look like this:
await page.waitForFunction(
() => [...document.images].every(image => image.complete),
{ timeout: 10_000 },
);
const imageStatus = await page.evaluate(() => [...document.images].map(image => ({
src: image.currentSrc || image.src,
complete: image.complete,
naturalWidth: image.naturalWidth,
})));
const failedImages = imageStatus.filter(image => image.complete && image.naturalWidth === 0);
if (failedImages.length) {
throw new Error(`Images failed: ${failedImages.map(image => image.src).join(', ')}`);
}
await page.screenshot({ path: 'page.png', fullPage: true });page.waitForFunction() waits for a page-context predicate to become truthy; page.evaluate() reads back the diagnostic state. The sample checks completion and then treats completed images with zero natural width as failures; adapt that policy if broken images are acceptable for your capture.
This check does not force lazy-loaded images to be requested. If relevant content is below the fold, bring it into view or use the application’s own readiness signal before waiting. Use a finite timeout: if it expires, report the URLs still incomplete and inspect their requests rather than waiting indefinitely. Pages with continuing background traffic may also make broad network-idle waits unsuitable; the network-idle API and its options describe the network-activity wait and its idle/concurrency settings.
4. Test cache and service workers only when evidence points there
If an image behaves differently between runs, or the site uses a service worker, compare a run that bypasses service workers. If a stale cached response is plausible, compare with cache disabled. Change one variable at a time so the result identifies a likely cause:
// Diagnostic comparison: run separately from the normal capture.
await page.setBypassServiceWorker(true);
await page.setCacheEnabled(false);
await page.goto(url, { waitUntil: 'networkidle2' });setBypassServiceWorker(true) ignores service workers for requests. setCacheEnabled(false) disables use of the browser cache; cache is enabled by default. These are diagnostic controls, not general image fixes. Restore normal settings after the comparison unless your capture requirements call for the changed behavior.
5. Match browser errors and URL restrictions to the failing request
When the error is net::ERR_BLOCKED_BY_CLIENT
This message is not a unique diagnosis for missing images. Puppeteer documents a Chrome for Testing HTTPS-first feature that can produce the error for a particular remote HTTP navigation scenario, including a warning page. First verify the failing URL and whether the failed operation is a top-level HTTP navigation or an image subresource. Do not apply the documented navigation workaround to an image unless the evidence matches. Details are in Puppeteer’s troubleshooting guide.
When Puppeteer connects to Chrome with URL allow/block patterns
If your connection uses Puppeteer’s experimental allowlist or blocklist URL patterns, check whether the image host matches. Matching subresource requests, including images, can fail. Puppeteer describes this feature as Chrome-only, based on URLPattern, and not a complete network sandbox; see ConnectOptions.
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 problems6. A practical troubleshooting order
- Reproduce one affected screenshot and record the image URL, request outcome, and browser error text.
- Inspect
document.imagesforsrc,complete, andnaturalWidth; account for lazy loading and the captured region. - Audit every request interception handler. Remove unintended image aborts and ensure requests intended to load are resolved.
- Wait on required image or application readiness with a finite timeout; report remaining or failed URLs if the wait does not succeed.
- Only if indicated, compare service-worker bypass or disabled cache, changing one diagnostic variable at a time.
- Check the specific Chrome error or configured URL patterns against the request type and URL.
Or skip the browser setup
ScreenshotNeo takes a website screenshot with one GET request. Cookie banners and consent prompts, newsletter popups, and chat widgets are removed before capture; those cleanup steps can each be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server gives AI agents tools to take screenshots, inspect page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Learn more at ScreenshotNeo.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Sign up free for 1,000 screenshots a month with no card.
Frequently Asked Questions
Does networkidle2 guarantee that every image loaded?
No. It indicates network idleness under Puppeteer’s wait conditions; check the required image elements and their success state separately.
Should I always disable the browser cache to fix missing screenshot images?
No. Disable it only as a controlled diagnostic when stale cache is plausible; cache and service-worker changes are not universal fixes.
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.
