Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

page.pdf() fails in Puppeteer with 'Printing is not available'

ErrorProtocolError: Protocol error (Page.printToPDF): Printing is not available

Short answer

The Puppeteer maintainers answer this error by saying that PDF printing needs headless mode, so page.pdf() fails when the browser is visible. Check three places: a launch with headless set to false, the devtools option, which forces headless off, and a connect() to an already running normal Chrome. Use a headless browser for the PDF.

  • Applies to Puppeteer (current docs), Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find how the browser is started or reached. Any of these words near the failing code tells you which cause applies.

    grep -rn "headless\|devtools\|puppeteer.connect\|browserWSEndpoint" --include=*.js --include=*.ts --include=*.mjs --exclude-dir=node_modules .
  2. 2Match what you see, then jump to its fix

    1. 1The PDF works when you remove the visible window, and fails as soon as headless is falseThe browser was launched with headless: falseFix
    2. 2The launch options do not say headless: false, but they set devtools: trueThe devtools option turns headless offFix
    3. 3The code uses puppeteer.connect with a browser endpoint, and that Chrome was started with a windowThe script connects to a normal Chrome that is already runningFix

What does the error look like?

  • ProtocolError: Protocol error (Page.printToPDF): Printing is not available

Cause 1 of 3

The browser was launched with headless: false

1Check

A visible browser is a headful one. The maintainers of Puppeteer answered this exact error by saying PDF printing needs headless mode. The default for the headless option is true.

grep -rn "headless: false\|headless:false" --include=*.js --include=*.ts --exclude-dir=node_modules .

2Fix

Launch headless for the PDF job. If you also need to watch a page, run that in a separate visible browser.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.pdf({ path: 'out.pdf', format: 'A4', printBackground: true });
await browser.close();

3Verify

The script finishes without a ProtocolError and the file exists.

node make-pdf.mjs
ls -l out.pdf

Confirmed by github.com

Did this fix it?

Cause 2 of 3

The devtools option turns headless off

1Check

The launch option devtools, when true, forces headless to false. A launch written for debugging therefore opens a visible browser even when headless is not mentioned.

grep -rn "devtools" --include=*.js --include=*.ts --exclude-dir=node_modules .

2Fix

Remove devtools from the launch that makes the PDF, or keep it only for a separate debugging session.

const browser = await puppeteer.launch({ headless: true });

3Verify

Run the script again; page.pdf() resolves.

node make-pdf.mjs

Confirmed by pptr.dev

Did this fix it?

Cause 3 of 3

The script connects to a normal Chrome that is already running

1Check

In a reported case a script attached to a visible Chrome and then failed with this error. The maintainers' answer was the same: PDF printing needs headless mode, and attaching does not change how the browser was started.

grep -rn "puppeteer.connect\|browserWSEndpoint" --include=*.js --include=*.ts --exclude-dir=node_modules .

2Fix

Let Puppeteer launch its own headless browser for the PDF, or start the shared browser in headless mode before you connect to it.

// start your own headless browser for the PDF step
const browser = await puppeteer.launch({ headless: true });

3Verify

page.pdf() writes the file without the ProtocolError.

ls -l out.pdf

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Keep PDF generation in its own function that always launches a headless browser, separate from any debugging session.
  • Read the headless setting from one config value, so a debugging override cannot reach production.
  • Pass format and printBackground explicitly; their defaults are letter and no backgrounds.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.