microsoft/playwright · error · Error

Could not connect to ${channel}.\n${remoteDebuggingHint(chan

Error message

Could not connect to ${channel}.\n${remoteDebuggingHint(channel)}

What it means

Thrown in Chromium.connectOverCDP when the WS-endpoint resolution + WebSocket connect fails AND the endpointURL was recognized as a Chromium channel name (e.g. 'chrome'). It surfaces a remote-debugging hint because connecting by channel name requires that browser already be running with remote debugging enabled.

Source

Thrown at packages/playwright-core/src/server/chromium/chromium.ts:111

      headersMap = headersArrayToObject(options.headers, false);

    if (!headersMap)
      headersMap = { 'User-Agent': getUserAgent() };
    else if (headersMap && !Object.keys(headersMap).some(key => key.toLowerCase() === 'user-agent'))
      headersMap['User-Agent'] = getUserAgent();

    const channel = isChromiumChannelName(endpointURL) ? endpointURL : undefined;
    if (channel)
      endpointURL = await resolveChannelEndpoint(progress, endpointURL);

    let wsEndpoint: string;
    let chromeTransport: WebSocketTransport;
    try {
      wsEndpoint = await urlToWSEndpoint(progress, endpointURL, headersMap);
      chromeTransport = await WebSocketTransport.connect(progress, wsEndpoint, { headers: headersMap, followRedirects: true, debugLogHeader: 'x-playwright-debug-log' });
    } catch (e) {
      if (channel)
        throw new Error(`Could not connect to ${channel}.\n${remoteDebuggingHint(channel)}`);
      throw e;
    }
    const closeAndWait = async () => await chromeTransport.closeAndWait();
    return this._connectOverCDPImpl(progress, chromeTransport, closeAndWait, options, onClose);
  }

  private async _connectOverCDPImpl(progress: Progress, transport: ConnectionTransport, closeAndWait: () => Promise<void>, options: types.LaunchOptions & { isLocal?: boolean, noDefaults?: boolean, artifactsDir?: string }, onClose?: () => Promise<void>) {
    let artifactsDir: string;
    const tempDirectories: string[] = [];
    if (options.artifactsDir) {
      artifactsDir = options.artifactsDir;
    } else {
      artifactsDir = await progress.race(fs.promises.mkdtemp(ARTIFACTS_FOLDER));
      tempDirectories.push(artifactsDir);
    }
    const doCleanup = async () => {
      await removeFolders(tempDirectories);
      const cb = onClose;

View on GitHub (pinned to c8fc3bf8d3)

Solutions

Launch Chrome with remote debugging yourself: 'chrome --remote-debugging-port=9222' and connect to 'http://localhost:9222'.
In Chrome, enable chrome://inspect 'Allow remote debugging for this browser instance' as the embedded hint suggests.
Connect by explicit wsEndpoint URL (ws://host:port/devtools/browser/...) instead of by channel name.

Example fix

// before
const b = await chromium.connectOverCDP('chrome');
// after
// shell: google-chrome --remote-debugging-port=9222
const b = await chromium.connectOverCDP('http://localhost:9222');

Defensive patterns

Strategy: validation

Validate before calling

async function probeCDP(httpURL: string): Promise<boolean> {
  try {
    const r = await fetch(httpURL + '/json/version');
    return r.ok && !!(await r.json()).webSocketDebuggerUrl;
  } catch { return false; }
}

Type guard

function isChannelName(url: string): boolean {
  return /^(chrome|msedge|chromium)/i.test(url) && !/^https?:\/\//.test(url);
}

Try / catch

try {
  browser = await chromium.connectOverCDP('chrome');
} catch (e) {
  if (/Could not connect to/.test(String(e.message))) {
    throw new Error('Start Chrome with --remote-debugging-port=9222, then connect by http URL');
  }
  throw e;
}

Prevention

Prefer connecting by explicit http/ws URL rather than channel name in production scripts.
Launch Chrome yourself with --remote-debugging-port so the endpoint is deterministic.

When it happens

Trigger: await chromium.connectOverCDP('chrome') (or 'msedge') when that browser is not running with --remote-debugging-port=0 / remote debugging enabled, or the DevToolsActivePort file is missing.

Common situations: Trying to attach to a user's already-running Chrome that was started normally (no debugging flag). Wrong/old user-data-dir. Browser launched by a desktop session that did not enable remote debugging.

Related errors

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