microsoft/playwright · error · Error

Could not connect to ${channel}: invalid DevToolsActivePort

Error message

Could not connect to ${channel}: invalid DevToolsActivePort file at ${devToolsActivePortPath}.

What it means

Thrown by resolveChannelEndpoint after reading the DevToolsActivePort file: its content is present but parseInt(contents.trim(), 10) returns NaN. The file exists but does not contain a parseable port number, indicating a corrupted or unexpected file at the channel's user-data-dir.

Source

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

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

async function seleniumErrorHandler(params: HTTPRequestParams, response: http.IncomingMessage) {
  const body = await streamToString(response);
  let message = body;
  try {
    const json = JSON.parse(body);
    message = json.value.localizedMessage || json.value.message;
  } catch (e) {
  }
  return new Error(`Error connecting to Selenium at ${params.url}: ${message}`);
}

function addProtocol(url: string) {

View on GitHub (pinned to c8fc3bf8d3)

Solutions

Delete the corrupted DevToolsActivePort file in the channel's user-data-dir and relaunch Chrome with remote debugging.
Use a clean/throwaway user-data-dir for Chrome: 'chrome --remote-debugging-port=9222 --user-data-dir=/tmp/cdp', then connect by http URL.
Connect by an explicit ws:// endpoint obtained from http://localhost:9222/json/version instead of by channel name.

Example fix

// before
const b = await chromium.connectOverCDP('chrome');
// after
// shell: rm -f "<channelUserDataDir>/DevToolsActivePort"
//        google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/cdp
const b = await chromium.connectOverCDP('http://localhost:9222');

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'fs';
function assertDevToolsPortValid(file: string) {
  const txt = fs.readFileSync(file, 'utf-8').trim();
  if (!Number.isInteger(parseInt(txt, 10)))
    throw new Error(`DevToolsActivePort at ${file} is not a valid port; delete it and relaunch Chrome`);
}

Type guard

function devToolsPortIsValid(txt: string): boolean {
  return Number.isInteger(parseInt(txt.trim(), 10));
}

Try / catch

try {
  browser = await chromium.connectOverCDP('chrome');
} catch (e) {
  if (/invalid DevToolsActivePort/.test(String(e.message))) {
    // delete the corrupted file and relaunch Chrome with a clean profile
  }
  throw e;
}

Prevention

Use a dedicated --user-data-dir for CDP so DevToolsActivePort is not contaminated.
Delete stale DevToolsActivePort files when Chrome did not shut down cleanly.

When it happens

Trigger: chromium.connectOverCDP('chrome') where the DevToolsActivePort file exists but contains non-numeric text (e.g. an error message written there, a partial write, or a file left by a different tool).

Common situations: A crashed/aborted Chrome left a malformed file. A custom channel build writes a different format. Another tool owns that path. Permissions issue causing a truncated read.

Related errors

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