mastra-ai/mastra · error · Error

No webSocketDebuggerUrl found in CDP version response from $

Error message

No webSocketDebuggerUrl found in CDP version response from ${versionUrl}

What it means

After fetching the CDP /json/version payload, resolveWebSocketUrl requires a webSocketDebuggerUrl field to know which WebSocket to attach to. If the JSON is valid but lacks that field, it throws. Some gateways or older/patched Chrome builds omit or mask this field.

Source

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

      this.logger.debug?.(`Resolving WebSocket URL from ${versionUrl}`);

      // Add timeout to prevent hanging on dead endpoints
      const controller = new AbortController();
      const timeoutId = setTimeout(() => controller.abort(), 10000);

      try {
        const response = await fetch(versionUrl, { signal: controller.signal });
        clearTimeout(timeoutId);

        if (!response.ok) {
          throw new Error(
            `Failed to fetch CDP version info from ${versionUrl}: ${response.status} ${response.statusText}`,
          );
        }

        const data = (await response.json()) as { webSocketDebuggerUrl?: string };
        if (!data.webSocketDebuggerUrl) {
          throw new Error(`No webSocketDebuggerUrl found in CDP version response from ${versionUrl}`);
        }

        this.logger.debug?.(`Resolved WebSocket URL: ${data.webSocketDebuggerUrl}`);
        return data.webSocketDebuggerUrl;
      } catch (error) {
        clearTimeout(timeoutId);
        if (error instanceof Error && error.name === 'AbortError') {
          throw new Error(`Timeout resolving WebSocket URL from ${versionUrl} (10s)`);
        }
        throw error;
      }
    }

    // Unknown protocol - return as-is and let the caller handle it
    return url;
  }

  // ---------------------------------------------------------------------------

View on GitHub (pinned to 75dd419e61)

Solutions

Pass the WebSocket URL directly (ws://host:port/devtools/browser/<id>) instead of the http version URL.
Launch Chrome with --remote-debugging-address=0.0.0.0 (and --remote-debugging-port) so the field is present and reachable.
Remove/fix any proxy that rewrites or strips /json/version fields.
Construct the ws URL manually from the host:port if the endpoint is known.

Example fix

// before
await browser.connectToExternalCdp('http://chrome:9222'); // version JSON lacks webSocketDebuggerUrl
// after
const res = await fetch('http://chrome:9222/json/version');
const { webSocketDebuggerUrl } = await res.json();
await browser.connectToExternalCdp(webSocketDebuggerUrl.replace('127.0.0.1', 'chrome'));

Defensive patterns

Strategy: type-guard

Validate before calling

const res = await fetch('http://host:9222/json/version');
const data: unknown = await res.json();
if (!isCdpVersionOk(data)) throw new Error('Endpoint does not advertise webSocketDebuggerUrl; pass ws URL manually');

Type guard

function isCdpVersionOk(d: unknown): d is { webSocketDebuggerUrl: string } {
  return typeof d === 'object' && d !== null && typeof (d as any).webSocketDebuggerUrl === 'string' && (d as any).webSocketDebuggerUrl.startsWith('ws');
}

Try / catch

try {
  await browser.connectToExternalCdp('http://chrome:9222');
} catch (err) {
  if (err instanceof Error && err.message.includes('No webSocketDebuggerUrl found')) {
    await browser.connectToExternalCdp('ws://chrome:9222/devtools/browser'); // hand-built URL
  } else throw err;
}

Prevention

Inspect /json/version output manually once per environment before automating.
Launch Chrome with --remote-debugging-port and a reachable bind address.
Avoid proxies that rewrite the version JSON.
Prefer direct ws:// endpoints in production.

When it happens

Trigger: The /json/version response JSON has no webSocketDebuggerUrl key — e.g. a proxy that rewrites Host headers without fixing the URL, a hardened/patched Chromium, or an intermediary that returns a trimmed version document.

Common situations: Docker/Kubernetes setups where Chrome binds 127.0.0.1 and the response advertises an unreachable host (some setups strip the field); proxying through services like Envoy/nginx that alter the JSON; non-Chrome CDP-compatible runtimes.

Related errors

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