Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Puppeteer PDF headers and footers are usually missing or misplaced for a small set of reasons: displayHeaderFooter is off, the template has no room in the page margins, print CSS changes the layout, or the selected paper size conflicts with your CSS. Start with an explicit PDF configuration, then work through media type, page geometry, templates, and font loading.
Start with a known-good PDF configuration
In Puppeteer 25.12.0, displayHeaderFooter defaults to false. Custom headers and footers are HTML strings, and an omitted margin leaves no margins configured. This baseline makes all three requirements explicit:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setContent(`
<!doctype html>
<html>
<head>
<style>
@page { size: Letter; margin: 0; }
body { font: 12pt Arial, sans-serif; margin: 0; }
.content { padding: 1in 0.75in; }
</style>
</head>
<body>
<main class="content">
<h1>Quarterly report</h1>
<p>Document content goes here.</p>
</main>
</body>
</html>
`, { waitUntil: 'networkidle0' });
await page.pdf({
path: 'report.pdf',
format: 'Letter',
printBackground: true,
displayHeaderFooter: true,
margin: {
top: '0.8in',
right: '0.75in',
bottom: '0.8in',
left: '0.75in'
},
headerTemplate: `
<div style="font-size:9px; width:100%; text-align:center; color:#555;">
Quarterly report
</div>`,
footerTemplate: `
<div style="font-size:9px; width:100%; text-align:center; color:#555;">
Page <span class="pageNumber"></span> of <span class="totalPages"></span>
</div>`
});
await browser.close();The margin values are not universal requirements; they are space reserved for the template in this example. Increase them if your header or footer is taller, and reduce them only after checking that content does not collide with the template.
Why a header or footer is missing
displayHeaderFooter was not enabled
The templates do nothing unless displayHeaderFooter: true is present. The documented default is false, so code that supplies only headerTemplate appears to ignore the header.
#1 Best Overall
- INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
- COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
- ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
- HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs
The wrong template option is being used
Use headerTemplate for the top area and footerTemplate for the bottom area. Both accept HTML. A malformed string, unclosed markup, or CSS that makes the content transparent can also look like an absent template. Begin with a plain text <div>, confirm it renders, and then add styling.
The template is outside the printable geometry
Headers and footers occupy the page’s margin areas. With no explicit margin, there may be no usable space. Set margin.top and margin.bottom to values that exceed the rendered template height. Keep the template’s CSS compact: use an inline font size, width, alignment, and color rather than relying on document stylesheets.
A print rule hides or changes the expected output
Page.pdf() generates the document with the print CSS media type. Rules in @media print, print-only stylesheets, and @page can therefore change dimensions, visibility, and spacing compared with the browser window. Search for declarations such as display:none, changed positioning, and print-specific margins.
Use dynamic values correctly
Puppeteer supports these special classes in header and footer templates:
Recommended Free Tools
| Class | Value inserted | Typical use |
|---|---|---|
date |
Generated date | Publication or export date |
title |
Page title | Document name |
url |
Page URL | Source address |
pageNumber |
Current page number | “Page 2” |
totalPages |
Total page count | “of 8” |
For example:
footerTemplate: `
<div style="width:100%; font-size:8px; padding:0 24px;">
<span class="title"></span>
<span style="float:right">
<span class="pageNumber"></span>/<span class="totalPages"></span>
</span>
</div>`
Do not expect arbitrary class names, JavaScript, or application variables to be replaced automatically. Render those values into the HTML string before calling page.pdf().
Make page size and CSS agree
Choose one paper model deliberately
The PDF options reference lists Letter as the default format. You can instead set format, or specify width and height. Decide whether the PDF is a standard paper document or a design whose exact dimensions come from CSS.
Rank #2
- CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
- INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
- PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
- ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴
Let @page win when CSS defines the design
Set preferCSSPageSize: true when the dimensions in your @page rule should take precedence over format, width, or height. Without that option, content is scaled to fit the selected paper size.
await page.pdf({
path: 'invoice.pdf',
displayHeaderFooter: true,
preferCSSPageSize: true,
margin: { top: '72px', bottom: '64px', left: '48px', right: '48px' },
headerTemplate: '<div style="font-size:9px;width:100%;text-align:right">Invoice</div>',
footerTemplate: '<div style="font-size:9px;width:100%;text-align:center">Page <span class="pageNumber"></span></div>'
});Prevent content from entering reserved space
A document’s body padding is not a substitute for PDF margins. The margin options reserve space for Puppeteer’s header and footer; body padding controls the document itself. Use both when you need a border or a consistent text inset, and inspect the first and last lines on every page for overlap.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose print or screen media intentionally
Print media is the default for PDF generation. If your screen layout is the intended source, select it immediately before generating the PDF:
await page.emulateMediaType('screen');
await page.pdf({
path: 'screen-layout.pdf',
displayHeaderFooter: true,
margin: { top: '72px', bottom: '72px' },
headerTemplate: '<div style="width:100%;font-size:9px">Screen header</div>',
footerTemplate: '<div style="width:100%;font-size:9px">Screen footer</div>'
});Use this only when screen rules are what you want. Otherwise, keep print media and fix the relevant @media print rules. A header can appear to “vanish” simply because its document counterpart is hidden in print CSS; the PDF template itself should still be tested with a minimal string.
Fonts, colors, and rendering timing
Fonts
Puppeteer documents waitForFonts: true as the default. PDF generation waits for fonts to load, but the documentation notes that a background page may need Page.bringToFront() for document.fonts.ready to resolve. If a header wraps differently, uses a fallback font, or changes height between runs, bring the page forward and verify the font request succeeds.
await page.bringToFront();
await page.evaluate(() => document.fonts.ready);
await page.pdf({
path: 'font-stable.pdf',
waitForFonts: true,
displayHeaderFooter: true,
margin: { top: '1in', bottom: '0.75in' },
headerTemplate: '<div style="font-family:Inter,sans-serif;font-size:10px;width:100%">Stable type</div>'
});The waitForFonts option was introduced in Puppeteer 22.13.0 (released July 11, 2024). Check your installed Puppeteer version before depending on version-specific behavior. If you intentionally disable font waiting, treat changed metrics as an expected trade-off rather than a header bug.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Rank #3
- SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
- INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
- KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
- PREMIUM SUPPORT - Strong technical expertise to solve issues faster
- THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.
Colors
PDF output colors are modified for printing by default. If the complaint is that a colored header looks washed out, use print-color adjustment in the page CSS:
@media print {
.brand-header {
-webkit-print-color-adjust: exact;
print-color-adjust: exact;
}
}This addresses color reproduction; it does not create missing space or fix clipping.
A systematic troubleshooting sequence
- Log the complete options object. Confirm
displayHeaderFooteris true, the intended template is non-empty, and top or bottom margins are explicit. - Reduce the template. Replace it with plain text in a single
<div>. If that works, add classes, images, and styling one change at a time. - Test dynamic classes separately. Verify
pageNumberandtotalPageswith a two-page document. Check spelling and capitalization. - Check page geometry. Record
format,width,height,preferCSSPageSize, and the@pagerule. Increase the relevant margin to prove whether clipping is geometric. - Inspect print CSS. Search for
@media print, print stylesheets,@page, transforms, and rules that alter visibility or font size. - Check readiness. Wait for navigation, fonts, images, and any application data before calling
page.pdf(). Bring a background page to the front when font readiness stalls. - Compare versions. Record Puppeteer and Chromium versions. Rendering differences can be version-specific; do not label an unexplained mismatch an undocumented browser bug without a minimal reproduction.
Common symptoms, causes, and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| No header or footer at all | Toggle omitted or false | Set displayHeaderFooter: true. |
| Text is cut off at the edge | Insufficient top or bottom margin | Increase the matching margin; simplify template height. |
| Body overlaps the footer | Reserved PDF margin is too small | Increase margin.bottom; do not rely only on body padding. |
| Page number is blank | Unsupported or misspelled class | Use the documented pageNumber and totalPages classes. |
| Layout differs from the browser | Print media rules | Fix print CSS or call emulateMediaType('screen'). |
| Paper size is unexpected | @page and PDF options disagree |
Set preferCSSPageSize according to which source should win. |
| Header height changes between runs | Font not ready or fallback metrics | Wait for fonts, bring the page forward, and verify font loading. |
| Color looks lighter than expected | Print color adjustment | Use -webkit-print-color-adjust: exact where appropriate. |
Build a minimal reproduction when the cause is unclear
Strip the case to one HTML file, one header, one footer, and a single page break. Record the installed Puppeteer version, browser version, full PDFOptions object, relevant print CSS, and whether the page was foreground or background. Then add the original CSS and assets incrementally. This separates an API configuration problem from an interaction in your application stylesheet.
Performance and reliability considerations
- Use
networkidle0or an explicit readiness condition only when the page can actually become idle; analytics and long polling can otherwise delay generation indefinitely. - Prefer deterministic local or cached assets for headers. A remote logo that has not loaded when the PDF starts can alter template height or leave an empty area.
- Keep templates small and inline. They are separate print fragments, not ordinary page DOM, so document selectors and application scripts should not be assumed to apply.
- Use explicit margins and page dimensions in production. Defaults can change the result when content, fonts, or Puppeteer versions change.
- Save a diagnostic PDF and the options used for failed jobs. A visual diff of the first and last page often reveals whether the defect is clipping, scaling, or media selection.
Or skip the browser setup
If you need a clean screenshot or PDF of a URL rather than a custom Puppeteer document, ScreenshotNeo provides a website screenshot API and MCP server. It accepts cookie and consent banners as 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 and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result.
One GET request returns PNG, JPEG, WebP, or PDF:
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 all options, including PDF paper size, margins, page ranges, custom CSS and JavaScript, waits, selectors, cookies, headers, geolocation, device presets, retina scale, blocking rules, caching, async webhooks, bulk capture, signed links, and usage reporting. An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
There is a free plan with 1,000 screenshots per month and no card. Paid plans start at $5 for 3,000 screenshots; every feature is included on every plan. Create a free ScreenshotNeo account.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.FAQ
Can a header template use normal page CSS?
Treat the template as an independent HTML fragment and include the essential inline styles. Do not assume selectors or scripts from the document will style it reliably.
Rank #4
- Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
- No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
- Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
- Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
- The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
Why does a footer show on page one but not later pages?
Check whether the content is actually being generated as one PDF page, then verify the template is supplied on the same page.pdf() call and that page geometry is not clipping later output. A two-page minimal reproduction isolates pagination effects.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Should I use format or @page?
Use format for a standard paper size. Use CSS dimensions with preferCSSPageSize: true when the stylesheet defines the authoritative page design.
Frequently Asked Questions
Can a header template use normal page CSS?
Treat the template as an independent HTML fragment and include the essential inline styles. Do not assume selectors or scripts from the document will style it reliably.
Why does a footer show on page one but not later pages?
Check whether the content is actually being generated as one PDF page, then verify the template is supplied on the same page.pdf() call and that page geometry is not clipping later output. A two-page minimal reproduction isolates pagination effects.
Should I use format or @page?
Use format for a standard paper size. Use CSS dimensions with preferCSSPageSize: true when the stylesheet defines the authoritative page design.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallQuick 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.
