Puppeteer UnsupportedOperation Errors: Causes and Fixes

UnsupportedOperation means the browser protocol Puppeteer is currently using does not support the method that was called. Start by finding the failing method and options, then identify the browser, Puppeteer version, and active protocol. Check that exact method and its options in the official WebDriver BiDi support guide. If the feature requires Chrome DevTools Protocol (CDP), use a compatible browser and CDP where possible, or change the task to an operation supported by the current protocol. There is no universal replacement for every unsupported method.

What the error means

Puppeteer’s API reference defines UnsupportedOperation as an error thrown when a method is not supported by the currently used protocol. The error identifies a capability mismatch; it does not name the cause by itself. The call site, browser, protocol selection, package version, and options provide the necessary context. See the UnsupportedOperation API reference.

Puppeteer supports both CDP and WebDriver BiDi. The defaults differ: Firefox uses BiDi by default, while Chrome uses CDP by default. Chrome can also be explicitly launched with BiDi. Since BiDi does not support every Puppeteer feature available over CDP, an explicit protocol override can make a previously working call fail.

Diagnose the protocol mismatch

Capture the complete failure. Note the exact method, arguments and options, the full error text, and the stack trace. Keep the call that fails; a method may work in one code path but not another.
Record the environment. Identify whether the browser is Chrome or Firefox, the installed Puppeteer version, and whether the protocol was explicitly selected. Defaults differ by browser, so do not infer the active protocol from the browser alone if your launch configuration sets one.
Check the support guide for the method and options. The BiDi guide has supported features, unsupported features, and caveats. Support for a method name does not necessarily mean every parameter or option is supported. Match the guide to the Puppeteer version installed in your project; the documentation and support matrix can change.
Pick a compatible route. If the operation needs CDP, use CDP with a compatible browser when possible. Otherwise, adapt the task to a supported operation if one exists. Some protocol-specific features have no equivalent, so verify before rewriting the call.
Reduce and report if documentation says it should work. Make a small reproduction and include the method and options, package version, browser, selected protocol, full error and stack. Report it to the Puppeteer issue tracker.

Check protocol selection in your launch code

For Chrome, the default is CDP. If your code explicitly chooses BiDi, review that setting first when a CDP-oriented method starts throwing. For example, the guide documents selecting BiDi like this:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  protocol: 'webDriverBiDi',
});

try {
  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());
} finally {
  await browser.close();
}

This example shows protocol selection; it does not imply that every Puppeteer method works over BiDi. If the failing method requires CDP, remove or change the explicit protocol selection only if the browser and task can use CDP. Firefox’s default is BiDi, so changing a protocol option may not be available as a practical fix for every Firefox workflow.

Examples of protocol-sensitive features

The official BiDi guide lists unsupported features and caveats. Examples in the guide include some page emulation methods, Page.createCDPSession() and other CDP-specific APIs, accessibility, coverage, tracing, selected response-body methods, drag-and-drop APIs, network-condition emulation, service-worker controls, page metrics, and screencasting. This list is version-sensitive; check the current guide for the exact method and package version rather than treating these examples as a permanent compatibility guarantee.

The guide also documents restrictions on some otherwise supported operations, including navigation options and screenshot or PDF parameters. A method appearing in a supported section does not establish that every option works with every protocol.

A concrete example: timezone emulation on Firefox

Puppeteer issue #13344 records Page.emulateTimezone() throwing on Firefox with WebDriver BiDi because CDP support was required. That report used Puppeteer 23.9.0 and was closed as “not planned.” It is a historical example tied to that reported setup, not proof that all current versions behave the same way. For a current project, check the support guide for its installed version.

Issue #14259 records an UnsupportedOperation involving BidiHTTPRequest.postData on Firefox. The report alone does not establish the current implementation status or a definitive fix. Use the current documentation and version-specific behavior to decide what to do.

Common errors and fixes

Symptom	Likely cause	What to do
A method throws only on Firefox	Firefox uses WebDriver BiDi by default, and the method may not be supported over BiDi.	Check the BiDi support guide for the exact method and options. Use a supported approach or a compatible browser/protocol if the task requires CDP.
A method used to work in Chrome but fails after a launch change	The launch code may explicitly select BiDi instead of Chrome’s CDP default.	Inspect the protocol setting. Choose CDP if the feature requires it and CDP is suitable for the workflow.
The method is listed as supported, but a particular call still fails	A specific option may be restricted, or the guide may describe a different Puppeteer version.	Check the caveats and option-level support, confirm the installed version, and reduce the call to a minimal reproduction.
The error message mentions CDP support	The operation requires CDP, but the active browser/protocol combination does not provide it.	Use a compatible CDP configuration if available; otherwise find a supported way to accomplish the task. Do not assume every feature has a fallback.
An old issue appears to describe the same error	The report may involve an older package version or a specific browser setup.	Compare its version and environment with yours, then confirm against current documentation before applying its conclusion.

Reliability, performance, and cost considerations

This error is about feature support, not evidence that the browser is broken or slow. Switching protocols to get past it can change which Puppeteer operations are available, so check the methods and options your workflow needs before changing a shared launch configuration. For a reliable diagnosis, record the protocol and version with failures, and keep a small reproduction for protocol-specific calls. The research sources do not establish a performance or cost advantage for one protocol, so choose based on required feature support and verify any operational trade-offs in your own environment.

Or skip the browser setup

If your task is to capture a webpage image rather than automate a protocol-specific browser feature, ScreenshotNeo provides a screenshot API and MCP server. Its API takes one GET request with a URL and returns an image or PDF. See the ScreenshotNeo API docs for its parameters.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted and removed, and known newsletter popups and chat widgets are removed before the shot.
Bot checks, blank pages, failed loads and cache hits are not billed; response headers say the page verdict and whether the request was billed.
An MCP server provides take_screenshot, get_page_info and capture_pdf for AI agents.
The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Does this error mean Puppeteer is outdated?

Not by itself. It means the active protocol does not support the method. Check the package version because support changes, but first identify the protocol and exact call.

Should I switch every project to CDP?

No general rule follows from this error. Choose the protocol based on the browser and features your project requires; consult the support guide for those features.

Can I catch the error and keep going?

You can catch an exception in application code, but catching it does not make the operation succeed. Use a fallback only when you have verified a supported alternative for that specific task.