“Invalid parameters” is a protocol symptom, not a single Puppeteer bug. The fix depends on the command named in the complete error, the field it rejects, the value’s type or shape, and the Puppeteer, browser, Node.js, and protocol versions involved. Copy the entire message and stack trace first; then correct the argument for that exact API call or align the versions and protocol mode.
Start with the complete error
A log containing only Invalid parameters is not enough to choose a repair. Puppeteer forwards many operations to Chrome DevTools Protocol (CDP) or WebDriver BiDi. Either protocol can reject a request when a required property is missing, a value has the wrong JavaScript type, an object has the wrong shape, or the browser does not support the command being sent.
Look for the text immediately after the protocol error. Examples include:
Protocol error (IO.read): Invalid parameters handle: string value expectedProtocol error (Emulation.setDeviceMetricsOverride): Invalid parameters ... integer expected- A message naming
scale,preferCSSPageSize,downloadThroughput, orpartitionKey.
That command and field are your diagnostic starting point. Do not apply a workaround for PDF generation to a viewport, cookie, or network-emulation call merely because all of them contain the same phrase.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errors#1 Best Overall
A repeatable diagnostic procedure
- Preserve the full context. Save the complete error, stack, the Puppeteer method you called, and the values passed to it. Include whether the call runs in a browser process, a serverless runtime, or a test runner.
- Identify the protocol command. Common examples in reports are
Page.printToPDF,IO.read,Network.emulateNetworkConditions, andEmulation.setDeviceMetricsOverride. A WebDriver BiDi error will usually be apparent from how the browser was launched or connected. - Inspect every argument’s type. Values read from environment variables, command-line arguments, JSON, HTML forms, and configuration files often arrive as strings. Convert numeric and Boolean values before passing them to Puppeteer.
- Check required fields and object shape. Compare the options object with the API documentation for the installed Puppeteer release and the protocol version exposed by the browser. A property with the right name but the wrong nesting is still invalid.
- Record versions and mode. Capture
puppeteer(orpuppeteer-core) version, Node.js version, Chromium or Chrome build, operating system, and whether the connection uses CDP or WebDriver BiDi. - Minimize the reproduction. Keep only browser launch, one page, and the failing method. Remove optional properties, then add them back one at a time. This identifies the first rejected value without confusing failures from unrelated code.
Common causes and precise repairs
PDF options are strings instead of numbers or Booleans
A frequent Page.printToPDF report involved scale and preferCSSPageSize. In that case, the values had the wrong types. scale must be numeric, while preferCSSPageSize must be Boolean. Omit optional properties when their defaults are suitable.
const pdfOptions = {
path: 'report.pdf',
scale: Number(process.env.PDF_SCALE ?? 1),
preferCSSPageSize: process.env.USE_CSS_PAGE_SIZE === 'true'
};
await page.pdf(pdfOptions);Validate conversions rather than allowing Number('') or a malformed value to become an unintended number:
const scale = Number(process.env.PDF_SCALE ?? '1');
if (!Number.isFinite(scale)) throw new Error('PDF_SCALE must be numeric');
const preferCSSPageSize = process.env.USE_CSS_PAGE_SIZE === 'true';
await page.pdf({ path: 'report.pdf', scale, preferCSSPageSize });This example addresses the type mismatch described in that community report; confirm the accepted range and option names against the Puppeteer version you installed.
PDF stream handles are invalid or no longer strings
Puppeteer issue #4609 (opened June 21, 2019) shows a different failure: IO.read rejected a handle because a string was expected. The report used Puppeteer 1.18.0, Node.js 8.10, Amazon Linux in AWS Lambda, page.setContent(), and page.pdf(). It demonstrates that a PDF stream error is not the same as a bad PDF option. The issue excerpt does not establish a universal current fix.
For this pattern, verify that the stream-reading code passes the handle returned by the current API unchanged, does not serialize it into an object or number, and does not reuse a handle after closing it. Try writing the PDF directly with path to separate stream handling from PDF generation:
Rank #2
await page.setContent(html, { waitUntil: 'networkidle0' });
await page.pdf({ path: '/tmp/report.pdf', format: 'A4' });If direct output works but a streaming implementation fails, reduce that implementation to the smallest read loop and check the installed Puppeteer/browser pair before changing application logic.
Network emulation has a missing or malformed property
Puppeteer issue #11841 (opened February 6, 2024) reported page.emulateNetworkConditions with download throughput, upload throughput, and latency, followed by a message about mandatory downloadThroughput. The report used Puppeteer ^21.11.0, Node.js 20.11.0, and Windows. It was closed as not reproducible and not planned, so it is evidence of one report, not proof of a general defect or a guaranteed workaround.
Check the exact option names and numeric values for your installed release. Do not pass a string copied from a configuration file:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →const downloadThroughput = Number(config.downloadThroughput);
const uploadThroughput = Number(config.uploadThroughput);
const latency = Number(config.latency);
for (const [name, value] of Object.entries({ downloadThroughput, uploadThroughput, latency })) {
if (!Number.isFinite(value)) throw new Error(`${name} must be numeric`);
}
await page.emulateNetworkConditions({
downloadThroughput,
uploadThroughput,
latency
});If the error still names a required field, print the final object immediately before the call and compare it with the API contract for that release. A report that cannot be reproduced should not be treated as a universal Puppeteer failure.
Cookie partitioning depends on protocol and browser compatibility
Puppeteer issue #12787 (opened July 18, 2024) concerned page.setCookie with partitionKey under WebDriver BiDi and Chrome. The issue discussion included a maintainer comment on July 24, 2024 that Puppeteer did not yet support Chrome M127, and a July 29 comment that the reported example required secure: true. Later comments distinguished BiDi from non-BiDi behavior.
Those comments are historical and specific to that setup. For a current failure:
- Confirm whether your connection is BiDi or CDP.
- Check the Puppeteer release’s stated browser support and the actual Chrome build.
- Ensure the cookie fields satisfy the browser’s security rules, including
securewhere required by the reported context. - Remove
partitionKeytemporarily. If ordinary cookies work, the failing property is isolated; do not assume a cookie workaround applies to another protocol.
Viewport dimensions must be integers in the expected object
A TechOverflow report from August 15, 2019 passed defaultViewport: '1920x1080' and received an error requiring integer width and height. A dimension string is not equivalent to the object Puppeteer expects.
Recommended Free Tools
const browser = await puppeteer.launch({
defaultViewport: { width: 1920, height: 1080, deviceScaleFactor: 1 }
});The same principle applies to page.setViewport(): pass numeric fields, not a display string. The report’s versions are historical, so verify current option names and defaults in your installed release.
Use the error’s command to choose the branch
| Command or API area | What to inspect first | Evidence and limits |
|---|---|---|
Page.printToPDF / page.pdf() |
Numeric and Boolean option types; optional properties that can be omitted | Community report about scale and preferCSSPageSize; verify your release |
IO.read |
String stream handle, handle lifetime, and streaming code | Issue #4609 from 2019; no universal current fix established |
Network.emulateNetworkConditions |
Required property names, numeric throughput/latency, final object shape | Issue #11841 was closed not reproducible |
Cookie setting with partitionKey |
BiDi versus CDP, Chrome/Puppeteer compatibility, security fields | Issue #12787 comments were historical and setup-specific |
Emulation.setDeviceMetricsOverride or viewport APIs |
Integer width and height inside the expected object |
2019 report; versions are historical |
Version and protocol checks
“Upgrade everything” is not a diagnosis. First capture the versions, then reproduce with a supported and internally consistent set. A browser upgrade can expose an unsupported protocol command; a Puppeteer upgrade can change option validation; switching from CDP to BiDi can change cookie serialization and required fields.
node --version
npm list puppeteer puppeteer-core
# Record the browser version printed by your launch environment as well.Pin the versions used in production, test the minimal reproduction against that pin, and read the release documentation for the protocol mode you actually enable. Do not use the 2024 Chrome M127 discussion as current compatibility guidance.
Validation, logging, and safer configuration
Log a redacted copy of the final options object immediately before the failing call. Never log cookies, authorization headers, or other secrets. Use explicit parsers for environment values:
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 reinstallfunction requiredInt(value, name) {
const n = Number(value);
if (!Number.isInteger(n)) throw new Error(`${name} must be an integer`);
return n;
}
const viewport = {
width: requiredInt(process.env.VIEWPORT_WIDTH, 'VIEWPORT_WIDTH'),
height: requiredInt(process.env.VIEWPORT_HEIGHT, 'VIEWPORT_HEIGHT')
};
await page.setViewport(viewport);When reducing a failing call, remove optional fields first, then add one field per run. This makes a protocol-level rejection attributable to one value instead of a large configuration object.
Troubleshooting checklist
- Only the phrase appears: capture the command, field text, stack, and complete request context.
- “String value expected” or “integer expected” appears: inspect values from environment variables, CLI flags, JSON, and forms; convert and validate them.
- A required field is reported missing: print the final object, check spelling and nesting, and compare the installed API contract.
- It fails only with BiDi: record protocol mode, browser build, and Puppeteer release; isolate protocol-specific fields such as cookie partitioning.
- It fails only after a browser update: test the previously pinned browser and review compatibility for the Puppeteer release before changing application code.
- A workaround from a forum changes nothing: confirm that it targets the same command and field; identical wording does not mean identical cause.
- The minimal call still fails: include the minimal script and version matrix in a bug report. State whether the failure is reproducible rather than labeling it a general defect.
Or skip the browser setup
If your goal is simply to obtain a clean website image or PDF rather than debug a browser protocol call, ScreenshotNeo provides a single HTTP request and an MCP server for AI agents. Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Claude, Cursor, and other MCP clients can use take_screenshot, get_page_info, and capture_pdf.
cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo documentation for the other capture options. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to try it.
FAQ
Is “Invalid parameters” a Puppeteer bug?
Not by itself. It is a protocol rejection shared by unrelated commands. The named command, field, types, versions, and protocol mode determine whether the cause is your request or a compatibility issue.
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 →Should I switch from Puppeteer to another automation library?
Usually not as a first step. Identify and validate the rejected argument, then test a minimal reproduction. A library change can hide the original type, shape, or protocol mismatch without explaining it.
Best Value
- Used Book in Good Condition
What information should a bug report contain?
Include the complete error and stack, minimal script, sanitized arguments, Puppeteer and Node.js versions, browser build, operating system, and CDP or WebDriver BiDi mode. State whether the issue reproduces after removing optional fields.
Frequently Asked Questions
Can I fix every Invalid parameters error by converting values to numbers?
No. Numeric conversion addresses only fields that require numbers. Other failures involve missing properties, Boolean values, object shape, stream-handle lifetime, cookie security, or protocol compatibility.
Why does the same script work in one environment but not another?
The browser build, Puppeteer release, Node.js runtime, operating system, and protocol mode can differ. Record that matrix and test the smallest failing call in both environments.
The Bottom Line
Read the protocol command and field named in the complete error, validate the exact argument types and required shape, then check browser/protocol compatibility. There is no single fix for every Puppeteer “Invalid parameters” message.
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.
