microsoft/playwright · error · Error

Playwright manages remote debugging connection itself.

Error message

Playwright manages remote debugging connection itself.

What it means

Thrown in Chromium._innerDefaultArgs when the user-supplied args contain '--remote-debugging-pipe'. Playwright itself drives the browser over a remote-debugging pipe (or websocket) and must own that channel; a user-supplied flag would conflict, so it is rejected.

Source

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

  override async defaultArgs(options: types.LaunchOptions, isPersistent: boolean, userDataDir: string) {
    const chromeArguments = this._innerDefaultArgs(options);
    chromeArguments.push(`--user-data-dir=${userDataDir}`);
    chromeArguments.push('--remote-debugging-pipe');
    if (isPersistent)
      chromeArguments.push('about:blank');
    else
      chromeArguments.push('--no-startup-window');
    return chromeArguments;
  }

  private _innerDefaultArgs(options: types.LaunchOptions): string[] {
    const { args = [] } = options;
    const userDataDirArg = args.find(arg => arg.startsWith('--user-data-dir'));
    if (userDataDirArg)
      throw this._createUserDataDirArgMisuseError('--user-data-dir');
    if (args.find(arg => arg.startsWith('--remote-debugging-pipe')))
      throw new Error('Playwright manages remote debugging connection itself.');
    if (args.find(arg => !arg.startsWith('-')))
      throw new Error('Arguments can not specify page to be opened');
    const chromeArguments = [...chromiumSwitches()];

    // See https://issues.chromium.org/issues/40277080
    chromeArguments.push('--enable-unsafe-swiftshader');

    if (options.headless) {
      chromeArguments.push('--headless');

      chromeArguments.push(
          '--hide-scrollbars',
          '--mute-audio',
          '--blink-settings=primaryHoverType=2,availableHoverTypes=2,primaryPointerType=4,availablePointerTypes=4',
      );
    }
    if (options.chromiumSandbox !== true)
      chromeArguments.push('--no-sandbox');

View on GitHub (pinned to c8fc3bf8d3)

Solutions

Remove '--remote-debugging-pipe' from args; Playwright adds the correct transport flag itself.
If you need a specific debugging transport, use the chromium built-in (pipe is default) — do not pass it explicitly.
Use chromium.connectOverCDP if you genuinely need a separate WebSocket debugging endpoint.

Example fix

// before
await chromium.launch({ args: ['--remote-debugging-pipe', '--no-sandbox'] });
// after
await chromium.launch({ args: ['--no-sandbox'] });

Defensive patterns

Strategy: validation

Validate before calling

function sanitizeArgs(args: string[]): string[] {
  if (args.some(a => a.startsWith('--remote-debugging-pipe')))
    throw new Error('Do not pass --remote-debugging-pipe; Playwright manages the transport');
  return args;
}

Type guard

function argsArePlaywrightSafe(args: string[]): boolean {
  return !args.some(a => a.startsWith('--remote-debugging-pipe'));
}

Prevention

Treat launchOptions.args as Playwright-supplemental flags only; never transport/debugging flags.
Review copied Chrome flags against Playwright's defaultArgs before adding them.

When it happens

Trigger: chromium.launch({ args: ['--remote-debugging-pipe'] }) or persistent context with the same arg.

Common situations: Copy-pasting Chrome launch flags from a non-Playwright tutorial. Trying to 'optimize' the connection by adding the pipe flag manually.

Related errors

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