For a page-level Chrome DevTools Protocol (CDP) session in Puppeteer, call await page.createCDPSession(). Use the returned session’s send() method for protocol commands and on() to listen for events; call detach() when finished. For a debuggable target that you are handling as a Puppeteer Target rather than a Page, create the session with target.createCDPSession().
Create and use a page-level CDP session
Puppeteer’s Page.createCDPSession() creates a CDP session attached to that page. A session is a raw interface to the browser’s DevTools protocol: send protocol method names and their parameters, and subscribe to protocol events. The following adapts Puppeteer’s documented Animation-domain example; confirm that the commands are supported by the browser and protocol version you use.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com');
const session = await page.createCDPSession();
try {
await session.send('Animation.enable');
session.on('Animation.animationCreated', event => {
console.log('Animation created', event);
});
const result = await session.send('Animation.getPlaybackRate');
console.log('Playback rate:', result.playbackRate);
await session.send('Animation.setPlaybackRate', { playbackRate: 2 });
} finally {
await session.detach();
}
} finally {
await browser.close();
}For the installed release’s method signatures and protocol notes, see the Puppeteer Page.createCDPSession() reference and its CDPSession reference. The API pages reviewed identify Puppeteer 25.12.0 for several methods; the CDPSession details also appear in the Next reference, so check the documentation matching your installed Puppeteer version.
Send commands and handle results
Call session.send(method, parameters) and await its promise. The method name is a protocol method such as Animation.getPlaybackRate; the resolved value contains that command’s result fields. Commands that take no parameters can be sent with just the method name, as with Animation.enable.
Listen for events
Register a listener with session.on(eventName, callback), using the protocol event name, such as Animation.animationCreated. Register listeners while the session is attached and before the event you need may occur. Event availability and payloads depend on the protocol supported by the browser.
Choose where to attach
Use a Page for page work
When your workflow already has a Puppeteer Page, page.createCDPSession() is the direct page-level method. Puppeteer marks Page.target() obsolete and points page-session users to Page.createCDPSession(); avoid using page.target().createCDPSession() as the preferred page recipe. See the Page.target() reference.
Use a Target for target-level work
A Puppeteer target is a debuggable entity; documented examples include a frame, page, or worker. If you already have the relevant Target and need a session attached to it, call await target.createCDPSession(). This is an attachment-point choice, not a general performance or reliability advantage over a page session. See Target.createCDPSession() and the Puppeteer API reference.
Detach and manage the session lifetime
Call await session.detach() once the commands and event listeners are no longer needed. After detachment the session cannot send messages and does not emit events. The nested try/finally structure in the example ensures cleanup even if a command fails, and closes the browser separately. Do not directly instantiate or subclass CDPSession; Puppeteer documents its constructor as internal.
Connect to an existing browser when needed
Creating a session from a page or target is separate from connecting Puppeteer to a browser. For an existing browser, Puppeteer’s ConnectOptions documents browserURL and browserWSEndpoint as connection settings. It also documents protocolTimeout for individual CDP calls, with a default of 180,000 milliseconds on the API page reviewed. That is a version-sensitive documented default, not a guarantee for every installed release; verify the options in the ConnectOptions reference for your version.
Troubleshoot common CDP session failures
- Unsupported operation or method: CDP commands depend on the active protocol. If Puppeteer reports
UnsupportedOperation, check whether the target browser’s protocol supports that operation and whether the method name and parameters match that protocol. - Commands fail after detaching: A detached session cannot send messages or emit events. Keep it attached for the full period in which commands and listeners are required; create a new session from the page or target if another session is needed.
- Connection closed: Puppeteer documents
ConnectionClosedErrorfor a closed underlying connection. Check whether the browser or its connection ended before the command completed; this is distinct from a protocol method returning an error. - Protocol command error: Puppeteer documents
ProtocolErrorfor protocol errors. Inspect the failing method, its parameters, the target, and the browser’s protocol support rather than treating every failure as a transport problem. - Wrong attachment point: Use the page method for a page workflow, or the target method when you are operating on a target directly. Do not use the obsolete
Page.target()route for the recommended page-level session.
For error and target details, consult the Puppeteer API reference; API behavior can vary with the installed Puppeteer and browser versions.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup:
If your goal is to retrieve a website screenshot rather than issue arbitrary CDP commands, ScreenshotNeo provides a one-request screenshot API. It is not a replacement for a raw CDP session. For a screenshot, call it with cURL:
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 parameters. Before capture, it accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. ScreenshotNeo also has an MCP server with take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
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 reinstallFrequently Asked Questions
Can a CDP session be used after calling detach()?
No. Detachment ends the session’s ability to send messages and emit events.
Should I construct a CDPSession directly?
No. Obtain one from a Puppeteer page or target; Puppeteer documents the constructor as internal.
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.
