microsoft/playwright · error · Error

Browser userDataDir is not supported in isolated mode.

Error message

Browser userDataDir is not supported in isolated mode.

What it means

Thrown by `validateBrowserConfig` when both `browser.isolated` and `browser.userDataDir` are set. Isolated mode creates a fresh ephemeral context per session, which is incompatible with a fixed userDataDir (a persistent profile); the combination is contradictory and rejected at config validation time.

Solutions

1. Choose one: drop `--isolated` to use the persistent `userDataDir`, or remove `userDataDir`/`--profile` to use isolated ephemeral contexts.
2. Audit config file, CLI flags, and env vars for any source setting the conflicting option.
3. Remember isolated mode is for parallel/fresh sessions; userDataDir is for a stable persistent profile — they are mutually exclusive by design.

Example fix

# before
playwright mcp --isolated --user-data-dir ~/profile
# after (persistent)
playwright mcp --user-data-dir ~/profile
# or (isolated)
playwright mcp --isolated

function validateBrowserOpts(opts: { isolated?: boolean; userDataDir?: string }) {
  if (opts.isolated && opts.userDataDir)
    throw new Error('Cannot combine isolated mode with a userDataDir; pick one.');
}

When it happens

Trigger: Passing `--isolated` together with `--user-data-dir`/`--profile` on the CLI, or setting both `isolated: true` and `userDataDir` in a config file / env. The check fires during `validateBrowserConfig`, which runs on every MCP and CLI config resolution.

Common situations: A config file sets `isolated: true` and the CLI also passes `--profile`; env var enables isolated while a config file sets userDataDir; user misunderstands isolated mode and tries to pin a profile on top of it.

Related errors

• Browser is already in use for
• Cannot use --mobile together with --device, pick one.
• clientCertificates.origin is required
• Device emulation is not supported with cdpEndpoint.
• "deviceScaleFactor" option is not supported with null…

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

Appendix: source

Thrown at packages/playwright-core/src/tools/mcp/config.ts:239

  return { channel: channel ?? 'chrome', executablePath, profileDirName };
}

async function validateBrowserConfig(browser: MergedConfig['browser']): Promise<FullConfig['browser']> {
  let browserName = browser.browserName;
  if (!browserName) {
    browserName = 'chromium';
    // Assign channel only if the browserName is not provided, otherwise assume full control to the user.
    if (browser.launchOptions.channel === undefined)
      browser.launchOptions.channel = 'chrome';
  }

  if (browserName === 'chromium' && browser.launchOptions.chromiumSandbox === undefined) {
    if (process.platform === 'linux') {
      // Downloaded chromium builds (undefined channel, 'chromium', 'chrome-for-testing') lack the setuid sandbox helper on linux.
      const { channel } = browser.launchOptions;
      browser.launchOptions.chromiumSandbox = channel !== undefined && channel !== 'chromium' && channel !== 'chrome-for-testing';
    } else {
      browser.launchOptions.chromiumSandbox = true;
    }
  }

  if (browser.isolated && browser.userDataDir)
    throw new Error('Browser userDataDir is not supported in isolated mode.');

  if (browser.initScript) {
    for (const script of browser.initScript) {
      if (!await fileExistsAsync(script))
        throw new Error(`Init script file does not exist: ${script}`);
    }
  }
  if (browser.initPage) {
    for (const page of browser.initPage) {
      if (!await fileExistsAsync(page))
        throw new Error(`Init page file does not exist: ${page}`);
    }
  }

View on GitHub (pinned to f1d33b5029)