If images appear in the browser but disappear from a Puppeteer PDF, first check print-specific CSS, then verify that each required image was requested, loaded, and decoded before calling page.pdf(). Puppeteer prints with print media by default, and network-idle waits do not confirm that every image succeeded.
Why Puppeteer PDFs can omit images
There are several distinct failure points: print styles can hide or reposition an image; its request may not start or may fail; the browser may not have decoded it by print time; or lazy loading may leave it unfetched. The right fix depends on which stage is failing.
As an Amazon Associate I earn from qualifying purchases.
Puppeteer’s Page.pdf() uses print CSS by default. If the page looks correct on screen but not in the PDF, inspect @media print rules first. Puppeteer documents how to emulate screen media when screen styling is what you want in the output: Puppeteer PDF generation.
Recommended Free Tools
Diagnose the image before changing the PDF options
Compare screen and print output
Look for print rules that set an image or its parent to display: none or visibility: hidden, change its size, move it off-page, or clip it. If screen styling is intended, emulate it before producing the PDF:
#1 Best Overall
- PORTABLE SCANNER FOR USE ON-THE-GO — The fastest and lightest mobile single-sheet-fed compact document scanner in its class¹
- QUICK DOCUMENT SCANNING ― This Epson ultra-fast scanner scans a single page as quickly as 5.5 seconds²; Windows and Mac compatible
- VERSATILE PAPER HANDLING ― Portable scanner scans documents up to 8.5 x 72 in; Also easily digitizes receipts and ID cards to make accounting, bookkeeping, and organizing simpler
- INTUITIVE, HIGH-SPEED SOFTWARE — Epson ScanSmart Software³ is a smart tool allowing you to easily scan, review, and save; Stay organized easily with the help of this Epson scanner
- EASY SETUP — USB-powered connect to your computer for quick and simple scanning; No batteries or external power supply required to operate portable document scanner; Standard Connectivity: USB 2.0
await page.emulateMediaType('screen');
await page.pdf({ path: 'output.pdf' });Use print media instead when the PDF is meant to follow the site’s print layout. The relevant Puppeteer API is documented in the Page class reference.
Check which image URL the browser selected
For responsive images, src and srcset may not tell you which asset was actually selected. Inspect currentSrc, along with completion and intrinsic dimensions:
const imageInfo = await page.evaluate(() => [...document.images].map((img) => ({
src: img.src,
srcset: img.srcset,
currentSrc: img.currentSrc,
complete: img.complete,
naturalWidth: img.naturalWidth,
naturalHeight: img.naturalHeight,
loading: img.loading
})));
console.log(imageInfo);currentSrc reports the URL selected by the browser. Check that URL in request and response diagnostics for failures, redirects, access restrictions, unsupported formats, or corrupt content. See MDN’s currentSrc reference and img element reference.
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 →Rank #2
- FAST SPEEDS - Scans color and black and white documents a blazing speed up to 16ppm (1). Color scanning won’t slow you down as the color scan speed is the same as the black and white scan speed.
- ULTRA COMPACT – At less than 1 foot in length and only about 1. 5lbs in weight you can fit this device virtually anywhere (a bag, a purse, even a pocket).
- READY WHENEVER YOU ARE – The DS-640 mobile scanner is powered via an included micro USB 3. 0 cable allowing you to use it even where there is no outlet available. Plug it into you PC or laptop and you are ready to scan.
- WORKS YOUR WAY – Use the Brother free iPrint&Scan desktop app for scanning to multiple “Scan-to” destinations like PC, Network, cloud services, Email and OCR. (2) Supports Windows, Mac and Linux and TWAIN/WIA for PC/ICA for Mac/SANE drivers. (3)
- OPTIMIZE IMAGES AND TEXT – Automatic color detection/adjustment, image rotation (PC only), bleed through prevention/background removal, text enhancement, color drop to enhance scans. Software suite includes document management and OCR software. (4)
Do not treat complete as proof of success
An image’s complete property can be true even when the image is broken. Check naturalWidth as well: zero means the image does not have a usable intrinsic width. MDN documents this distinction in its complete property reference and HTMLImageElement reference.
Separate image elements from other graphics
The image readiness code below covers ordinary <img> elements. A CSS background image, canvas, iframe, or application-generated graphic has a different loading path; add a check appropriate to that content instead of assuming document.images covers it.
Wait for required images to load and decode
Wait for the images the PDF actually needs, then fail visibly if any image could not be used. img.decode() resolves when image data is ready for use and can reject if the request failed, the source changed, or the data is corrupt. The following helper makes those failures explicit instead of silently printing a partial document:
Rank #3
- STAY ORGANIZED – Easily convert your paper documents into digital formats like searchable PDF files, JPEGs, and more.Power Consumption : 2.5W or less (Energy Saving Mode: 0.7W). Suggested Daily Volume : 500 scans..Does it contain liquid: no
- CONVENIENT AND PORTABLE –lightweight and small in size, you can take the scanner anywhere from home offices, classrooms, remote offices, and anywhere in between
- HANDLES VARIOUS MEDIA TYPES – Digitize receipts, business cards, plastic or embossed cards, reports, legal documents, and more
- FAST AND EFFICIENT – No technical hurdles or complicated setups here; easily scan both sides of a document at the same time, in color or black-and-white, at up to 12 pages-per-minute, and with a 20 sheet automatic feeder
- BROAD COMPATIBILITY – Works with both Windows and Mac devices, be it laptop or computer
async function waitForRequiredImages(page) {
return page.evaluate(async () => {
const images = [...document.images];
// Ask native lazy-loaded images to load before waiting.
for (const img of images) {
if (img.loading === 'lazy') img.loading = 'eager';
}
await Promise.all(images.map(async (img) => {
if (!img.complete) {
await new Promise((resolve) => {
img.addEventListener('load', resolve, { once: true });
img.addEventListener('error', resolve, { once: true });
});
}
if (img.naturalWidth === 0) {
throw new Error(`Image failed or has no usable data: ${img.currentSrc || img.src}`);
}
await img.decode();
}));
return images.length;
});
}Use it after navigation has reached the point at which the page has produced its image elements, but before PDF generation:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
await waitForRequiredImages(page);
await page.pdf({ path: 'output.pdf' });Adapt the failure policy if some images are optional. For a PDF where every image is required, letting the helper throw is safer than swallowing a decode rejection. MDN documents decode() behavior at HTMLImageElement.decode().
Account for lazy loading and network-idle waits
Native lazy-loaded images may not be requested until they are near the viewport. The document load event is based on eager-loaded images, so it is not a guarantee that offscreen lazy images needed by a full-length PDF have loaded. Setting native loading="lazy" images to eager, as above, may help; pages with custom lazy-loading scripts may require an intentional scroll strategy or an application-level setting. Verify readiness after triggering the site’s own loader. MDN describes the loading property.
Rank #4
- IRIScan Express, portable scanner : scans color and black and white documents a blazing speed up to 8ppm simplex. Color scanning won’t slow you down as the color scan speed is the same as the black and white scan speed.
- IRIScan Express mobile scanner is powered via an included micro USB 2. 0 cable allowing you to use it even where there is no outlet available. Plug it into you PC or laptop and you are ready to scan. USB cable provided. AC Adapter not provided and not needed.
- IRIScan flatbed scanner uses a simplex scanning mode allows for quick and straightforward scanning of single-sided documents. IRIScan with its full portable features is the ideal document scanners for computers.
- IRIScan document scanner : Versatile scanning capabilities, including scanning to Word, PDF, and Excel formats with companion software provided Readiris OCR
- Receipt scanner and card scanner with Additional features include scanning business cards directly to Outlook, photo scanning, and receipt scanning for efficient document management
waitUntil: 'networkidle0' and waitUntil: 'networkidle2' use network-connection thresholds sustained for at least 500 ms. They can help when a page is still making requests, but they do not certify that each expected image succeeded. Pair them with an image-specific check. See Puppeteer’s lifecycle event documentation and waitForNetworkIdle API.
Generate the PDF after the checks
Here is a complete example using a Puppeteer browser instance. Replace the URL and output path as needed:
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11const puppeteer = require('puppeteer');
async function waitForRequiredImages(page) {
return page.evaluate(async () => {
const images = [...document.images];
for (const img of images) {
if (img.loading === 'lazy') img.loading = 'eager';
}
await Promise.all(images.map(async (img) => {
if (!img.complete) {
await new Promise((resolve) => {
img.addEventListener('load', resolve, { once: true });
img.addEventListener('error', resolve, { once: true });
});
}
if (img.naturalWidth === 0) {
throw new Error(`Image failed or unavailable: ${img.currentSrc || img.src}`);
}
await img.decode();
}));
});
}
(async () => {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
await waitForRequiredImages(page);
await page.pdf({ path: 'output.pdf', format: 'A4', printBackground: true });
} finally {
await browser.close();
}
})();The example sets printBackground: true for CSS background graphics. That option is separate from fetching ordinary <img> files: its documented default is false. Current documented PDF options also default waitForFonts to true, but font readiness does not establish image readiness. Check the PDFOptions reference for options and the documentation matching your installed Puppeteer version; the PDF guide cited here is on the next documentation track.
Best Value
- Scanner type: Document
- Connectivity technology: USB
- With Auto Scan Mode, the scanner automatically detects what you're scanning
- Digitize documents and images
If you use page.setContent(), its lifecycle wait options can help with page setup, but successful completion still does not prove every image loaded and decoded. Use the same image checks afterward. See Page.setContent().
Troubleshoot by symptom
| Symptom | Likely cause | What to check or change |
|---|---|---|
| Image is visible on screen but absent from PDF | Print media CSS changes visibility, layout, or clipping. | Inspect @media print rules. Emulate screen media only if screen styling is the intended PDF output. |
complete is true but the image is broken |
complete is not a success indicator. |
Check naturalWidth, currentSrc, request status, and decode errors. |
| Some images near the top appear, but offscreen images do not | Lazy loading has not requested images needed farther down the document. | Trigger the page’s lazy-loading mechanism or configure it to load the images needed for the PDF, then verify them. |
| Network idle occurs but images are still missing | Network idle tracks connection activity, not successful decoding of each expected image. | Wait on the required image elements and surface failed requests or decode rejections. |
| An image works in one viewport but not another | Responsive source selection may choose a different asset. | Inspect currentSrc and test that selected URL for access, redirects, and valid image data. |
| CSS illustration or embedded graphic is missing | It may be a background, canvas, frame, or application-generated resource rather than an <img>. |
Add a readiness check for that resource type; the image-element helper does not cover it. |
Or skip the browser setup
For a hosted screenshot or PDF workflow, ScreenshotNeo offers a one-request API and an MCP server for AI agents. Its cleanup can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, or another MCP client.
Example cURL request (replace the URL and API key):
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 problemscurl -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 details. One call avoids setting up the browser in your application; it does not replace diagnosing a page whose source assets or print layout are broken. ScreenshotNeo includes 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Sign up for free.
Frequently Asked Questions
Can a Puppeteer PDF wait for images with a single built-in option?
The documented PDF options include font waiting, but not a guarantee that every image loaded and decoded. Use an image-specific readiness check before calling page.pdf().
Does printBackground: true fix missing <img> files?
No. It controls CSS background printing; it does not establish that ordinary image elements fetched or decoded successfully.
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.
