microsoft/playwright · error · Error

Connecting to ${channel} by channel name is not supported on

Error message

Connecting to ${channel} by channel name is not supported on ${process.platform}.

What it means

Thrown by resolveChannelEndpoint when defaultUserDataDirForChannel(channel) returns nothing for the current platform. Connecting by channel name requires Playwright to know where that channel writes its user-data directory on this OS; if it does not, the channel-by-name path is unsupported.

Source

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

  const url = new URL(endpointURL);
  if (!url.pathname.endsWith('/'))
    url.pathname += '/';
  url.pathname += 'json/version/';
  const httpURL = url.toString();

  const json = await fetchData(progress, {
    url: httpURL,
    headers,
  }, async (_, resp) => new Error(`Unexpected status ${resp.statusCode} when connecting to ${httpURL}.\n` +
    `This does not look like a DevTools server, try connecting via ws://.`)
  );
  return JSON.parse(json).webSocketDebuggerUrl;
}

async function resolveChannelEndpoint(progress: Progress, channel: string): Promise<string> {
  const userDataDir = defaultUserDataDirForChannel(channel);
  if (!userDataDir)
    throw new Error(`Connecting to ${channel} by channel name is not supported on ${process.platform}.`);

  const devToolsActivePortPath = path.join(userDataDir, 'DevToolsActivePort');
  progress.log(`<ws preparing> reading ${devToolsActivePortPath}`);

  const contents = await progress.race(fs.promises.readFile(devToolsActivePortPath, 'utf-8').catch(() => undefined));
  if (!contents) {
    throw new Error(
        `Could not connect to ${channel}: DevToolsActivePort file not found at ${devToolsActivePortPath}.\n` +
        remoteDebuggingHint(channel));
  }

  const port = parseInt(contents.trim(), 10);
  if (isNaN(port))
    throw new Error(`Could not connect to ${channel}: invalid DevToolsActivePort file at ${devToolsActivePortPath}.`);

  const endpoint = `ws://localhost:${port}/devtools/browser`;
  progress.log(`<ws preparing> resolved channel "${channel}" to ${endpoint}`);
  return endpoint;

View on GitHub (pinned to c8fc3bf8d3)

Solutions

Connect by explicit WebSocket URL instead of channel name: launch Chrome with --remote-debugging-port=9222 and chromium.connectOverCDP('http://localhost:9222').
Use a channel name that is supported on this platform, or fall back to launching Chromium through Playwright rather than attaching to a channel.
On unsupported OS, manage the user-data-dir yourself and expose the WS endpoint directly.

Example fix

// before
const b = await chromium.connectOverCDP('chrome');
// after (platform without channel mapping)
// shell: chromium --remote-debugging-port=9222 --user-data-dir=/tmp/cdp
const b = await chromium.connectOverCDP('http://localhost:9222');

Defensive patterns

Strategy: validation

Validate before calling

function assertChannelSupportedOnPlatform(channel: string) {
  // channel-by-name connect needs a known userDataDir on this OS
  const known = process.platform === 'win32' || process.platform === 'darwin'; // chrome/msedge profile paths
  if (!known) throw new Error(`Channel '${channel}' connect not supported on ${process.platform}; use wsEndpoint URL`);
}

Type guard

function channelConnectSupportedOnPlatform(): boolean {
  return process.platform === 'win32' || process.platform === 'darwin';
}

Prevention

On Linux, prefer connecting by explicit http/ws URL over channel name.
Make the connect target an explicit endpoint to stay platform-independent.

When it happens

Trigger: await chromium.connectOverCDP('chrome') on a platform where the channel-to-userDataDir mapping is not defined (e.g. some Linux distros or uncommon channels).

Common situations: Cross-OS script that uses a channel name; works on macOS/Windows but throws on a Linux without a known profile path. Using a channel name that is not in the chromiumChannels registry for this platform.

Related errors

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