No webSocketDebuggerUrl found in CDP version response from $

Error message

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

What it means

After a successful HTTP fetch of the CDP /json/version endpoint, the library expects a webSocketDebuggerUrl field in the JSON response. If the response parses but lacks this field, it throws, because without the WebSocket debugger URL there is no way to attach to the browser. This indicates the endpoint answered but did not expose a connectable browser.

Source

Thrown at browser/firecrawl/src/resolve-cdp.ts:32

    const versionUrl = `${baseUrl}/json/version`;

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

    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

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

      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}`);
      }

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

  return url;
}

View on GitHub (pinned to 75dd419e61)

Solutions

Create a new Firecrawl browser session and retry — the old one is likely dead
Verify versionUrl/apiUrl actually points at a Chrome DevTools Protocol endpoint
Log/inspect the raw response body to see what was returned instead
Check for proxies or custom apiUrl mangling the CDP response

Defensive patterns

Strategy: retry

Validate before calling

const res = await fetch(versionUrl);
const data = await res.json();
if (!data.webSocketDebuggerUrl) console.error('Endpoint is not a CDP server:', data);

Type guard

function isCdpVersion(v: unknown): v is { webSocketDebuggerUrl: string } {
  return typeof v === 'object' && v !== null && 'webSocketDebuggerUrl' in v &&
    typeof (v as any).webSocketDebuggerUrl === 'string';
}

Try / catch

try {
  const browser = new FirecrawlBrowser(config);
} catch (e) {
  if (e instanceof Error && e.message.includes('No webSocketDebuggerUrl')) {
    await recreateBrowserSession(); // endpoint answered but no browser attached
  } else throw e;
}

Prevention

Point apiUrl at the actual CDP endpoint, not a proxy/error page
Create fresh sessions rather than caching version URLs
Log the raw JSON response when the error occurs
Avoid intermediaries that rewrite CDP responses

When it happens

Trigger: Constructor or wsUrl call where the CDP version endpoint returns JSON without webSocketDebuggerUrl — e.g. an intermediate gateway/proxy returns its own JSON, or the remote browser is not actually running.

Common situations: Firecrawl session terminated so the URL now points at a load balancer or error page that still returns JSON; wrong apiUrl hitting a non-CDP service; CDN/proxy stripping the field.

Related errors

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