Guides / Puppeteer PDFs in production
Puppeteer PDFs in production: what breaks
Five lines of code work on your laptop. Here's what tends to go wrong once real traffic hits it, and how to fix each one.
This is how most HTML-to-PDF setups start:
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setContent(html, { waitUntil: "networkidle0" });
const pdf = await page.pdf({ format: "A4", printBackground: true });
await browser.close();It's a good start. Below are the problems teams usually hit next. We run Chromium for PDFs ourselves, so this list comes from practice.
1. Launching a browser per request
Starting Chromium for each PDF adds latency and CPU spikes. Keep one browser running and open a fresh, isolated context (incognito context in Puppeteer, browser.newContext() in Playwright) per render, then close the context. Restart the browser if it crashes or after a set number of renders.
2. Memory and concurrency
Each open page uses real memory, and large tables or images use much more. Without a limit, a burst of requests can push the container out of memory. Put renders behind a queue or semaphore with a fixed concurrency, and return a retryable error (such as 503) when the queue is full instead of piling on.
3. Missing fonts in Docker
Slim base images ship with few or no fonts, so PDFs fall back to a default face or show boxes for emoji and non-Latin text. Install the font packages you need in the image (and an emoji font if users can type emoji), or embed fonts in the HTML as base64 @font-face.
4. Hanging renders
networkidle0 waits for every network request to finish, so one slow image or tracking script can stall a render. Set an overall timeout on the whole render, not just navigation, and prefer inlined assets with waitUntil: "load".
5. Rendering untrusted HTML (SSRF)
If users or customers control any part of the HTML, a headless browser on your network can be pointed at internal services: http://169.254.169.254/ cloud metadata, admin panels, file:// paths. Block every request except data: URIs (request interception or route()), keep JavaScript off unless you need it, and run the browser in a sandboxed container with no access to internal networks.
6. Page size and breaks
Chromium uses the format you pass to page.pdf() over CSS @page { size } unless you set preferCSSPageSize: true. Rows split across pages unless you add print CSS. See CSS page breaks for PDFs.
7. Keeping it patched
Chromium ships security fixes often. A browser that renders untrusted input is exactly the thing to keep current, which means regular image rebuilds and testing your PDFs after each one.
Self-host or use an API?
Self-host if you render very high volumes, need fully offline processing, or already run Chromium well. Open-source options such as Gotenberg package much of the above for you. Use an API if PDFs are a side feature and you'd rather not own a browser fleet. SlipKiln handles the queue, timeouts, fonts and network lockdown, and costs $0 for 50 documents a month, $9 for 1,000, or $19 for 3,000.
Related
Updated November 2026.