mastra-ai/mastra · error · Error

${this.provider} does not support connecting to external CDP

Error message

${this.provider} does not support connecting to external CDP

What it means

connectToExternalCdp is a base-class stub on MastraBrowser. Only providers that implement external CDP support override it; the default implementation always throws, stating which provider lacks support. Attaching to an externally running Chrome instance is opt-in per provider.

Source

Thrown at packages/core/src/browser/browser.ts:824

    return this._closePromise;
  }

  /**
   * Connect to an external browser via CDP URL for screencast.
   *
   * Use this when an agent is using their own external CDP (e.g., browser-use cloud).
   * Connects Playwright to the external browser to enable screencast without launching
   * our own browser.
   *
   * Override this in subclasses that support external CDP connections.
   * The base implementation throws an error.
   *
   * @param cdpUrl - The external CDP WebSocket URL (wss://... or ws://...)
   * @param threadId - Thread ID to associate the session with
   */
  async connectToExternalCdp(_cdpUrl: string, _threadId?: string): Promise<void> {
    throw new Error(`${this.provider} does not support connecting to external CDP`);
  }

  /**
   * Ensure the browser is ready, launching if needed.
   * If browser was previously closed, it will be re-launched.
   */
  async ensureReady(): Promise<void> {
    if (this.status === 'ready') {
      // Check if browser is still alive (handles external closure)
      // checkBrowserAlive() should save lastBrowserState internally if it detects closure
      const stillAlive = await this.checkBrowserAlive();
      if (stillAlive) {
        return;
      }
      // Browser was externally closed, mark as closed for re-launch
      this.status = 'closed';
    }
    if (this.status === 'pending' || this.status === 'error' || this.status === 'closed') {

View on GitHub (pinned to 75dd419e61)

Solutions

Use a provider that implements connectToExternalCdp for external CDP attach.
Check the provider's API surface/docs for CDP support before calling.
Launch a managed browser instead of attaching externally.
Implement the override on a custom provider subclass.

Example fix

// before
await unsupportedBrowser.connectToExternalCdp('ws://localhost:9222/...');
// after
const browser = new CdpCapableBrowser({ provider: 'agent-browser' });
await browser.connectToExternalCdp('ws://localhost:9222/devtools/browser/...');

Defensive patterns

Strategy: validation

Validate before calling

// capability check before attach
if (browser.connectToExternalCdp === MastraBrowser.prototype.connectToExternalCdp) {
  throw new Error(`Provider ${browser.provider} cannot attach to external CDP`);
}
await browser.connectToExternalCdp(cdpUrl, threadId);

Type guard

interface CdpCapable { connectToExternalCdp(url: string, threadId?: string): Promise<void>; }
function isCdpCapable(b: object): b is object & CdpCapable {
  return b.connectToExternalCdp !== MastraBrowser.prototype.connectToExternalCdp;
}

Try / catch

try {
  await browser.connectToExternalCdp(url);
} catch (err) {
  if (err instanceof Error && err.message.endsWith('does not support connecting to external CDP')) {
    // fall back to managed launch
    await browser.launch();
  } else throw err;
}

Prevention

Check provider docs for CDP attach support before designing around it.
Feature-detect via prototype comparison rather than calling and catching.
Keep a capability matrix of providers your app relies on.
Pin the provider type in config so unsupported code paths are unreachable.

When it happens

Trigger: Calling browser.connectToExternalCdp(cdpUrl, threadId?) on a provider subclass that has not overridden the method (e.g. a Playwright/agent-browser provider without CDP attach support).

Common situations: Assuming all providers can attach to an existing Chrome DevTools endpoint; migrating code from a CDP-capable provider to one that launches its own browser; passing a browserops endpoint string expecting it to be honored.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/3514e6755046c978. Report an issue: GitHub.