microsoft/playwright · error · Error

Connecting over CDP is only supported in Chromium and WebKit

Error message

Connecting over CDP is only supported in Chromium and WebKit.

What it means

Thrown inside connectOverCDP() when the first overload resolves to a ConnectionTransport (detected via isConnectionTransport: has send & close functions) but the BrowserType is not chromium or webkit. CDP transport connections are only implemented for those two engines; firefox is rejected.

Source

Thrown at packages/playwright-core/src/client/browserType.ts:151

      const browser = await connectToBrowser(this._playwright, { browserName: this.name(), ...params });
      browser._connectToBrowserType(this, {}, undefined);
      return browser;
    });
  }

  async connectOverCDP(options: api.ConnectOverCDPOptions  & { wsEndpoint?: string }): Promise<api.Browser>;
  async connectOverCDP(endpointURL: string, options?: api.ConnectOverCDPOptions): Promise<api.Browser>;
  async connectOverCDP(transport: api.ConnectOverCDPTransport, options?: api.ConnectOverCDPOptions): Promise<api.Browser>;
  async connectOverCDP(overloaded: (api.ConnectOverCDPOptions & { wsEndpoint?: string }) | string | api.ConnectOverCDPTransport, options?: api.ConnectOverCDPOptions): Promise<Browser> {
    let endpointURL: string | undefined;
    let transport: api.ConnectOverCDPTransport | undefined;
    let params: api.ConnectOverCDPOptions;
    if (typeof overloaded === 'string') {
      endpointURL = overloaded;
      params = options ?? {};
    } else if (isConnectionTransport(overloaded)) {
      if (this.name() !== 'chromium' && this.name() !== 'webkit')
        throw new Error('Connecting over CDP is only supported in Chromium and WebKit.');
      if (this._connection.isRemote())
        throw new Error('Passing a ConnectionTransport to connectOverCDP is not supported when connecting remotely.');
      transport = overloaded;
      params = options ?? {};
    } else {
      endpointURL = 'endpointURL' in overloaded ? (overloaded as any).endpointURL : overloaded.wsEndpoint;
      assert(endpointURL, 'Cannot connect over CDP without wsEndpoint.');
      params = overloaded;
    }
    if (endpointURL && this.name() !== 'chromium' && this.name() !== 'webkit')
      throw new Error('Connecting over CDP is only supported in Chromium and WebKit.');

    const result = await this._channel.connectOverCDP({
      endpointURL,
      transport: transport as any,
      headers: params.headers ? headersObjectToArray(params.headers) : undefined,
      slowMo: params.slowMo,
      isLocal: params.isLocal,

View on GitHub (pinned to c8fc3bf8d3)

Solutions

Use chromium or webkit for CDP transport connections.
For firefox use the WS endpoint overload of connectOverCDP (only chromium/webkit still apply), or the standard connect() API.
Gate the call on browserType.name() before invoking.

Example fix

// before
await firefox.connectOverCDP({ send, close });
// after
await chromium.connectOverCDP({ send, close });

Defensive patterns

Strategy: type-guard

Validate before calling

if (browserType.name() !== 'chromium' && browserType.name() !== 'webkit')
  throw new Error('connectOverCDP with a transport requires chromium or webkit.');

Type guard

function supportsCdpTransport(bt: any): boolean {
  const n = bt?.name?.();
  return n === 'chromium' || n === 'webkit';
}

Prevention

Gate CDP transport usage on browser name.
Use the WS endpoint overload where possible; it has the same engine restriction.

When it happens

Trigger: Calling `firefox.connectOverCDP({ send, close })` with a transport object. The branch `isConnectionTransport(overloaded)` is taken, then `this.name() !== 'chromium' && this.name() !== 'webkit'` is true for firefox.

Common situations: Generic code that picks a BrowserType dynamically and assumes CDP works for all; switching a transport-based integration from chromium to firefox without changing the connection method.

Related errors

AI-assisted analysis of microsoft/playwright@c8fc3bf8d3 (2026-08-12). Data as JSON: /api/errors/ddb7f22d76081fd8. Report an issue: GitHub.