microsoft/playwright · critical · Error

Missing system dependencies required to run browser ${browse

Error message

Missing system dependencies required to run browser ${browserName}. Install them with: sudo npx playwright install-deps ${browserName}

What it means

Thrown during `launchPersistentContext` when the underlying error message contains `cannot open shared object file: No such file or directory` — the classic Linux symptom of missing shared libraries (libnss3, libatk, etc.) required by the browser binary. The message remaps it to a friendlier hint with the `install-deps` command.

Source

Thrown at packages/playwright-core/src/tools/mcp/browserFactory.ts:189

    ...config.browser.contextOptions,
    handleSIGINT: false,
    handleSIGTERM: false,
    ignoreDefaultArgs: configIgnoreDefaultArgs === true
      ? true
      : [
        '--disable-extensions',
        ...Array.isArray(configIgnoreDefaultArgs) ? configIgnoreDefaultArgs : [],
      ],
  };
  try {
    const browserContext = await browserType.launchPersistentContext(userDataDir, launchOptions);
    const browser = browserContext.browser()!;
    return browser;
  } catch (error: any) {
    throwIfExecutableMissing(error, config);
    if (error.message.includes('cannot open shared object file: No such file or directory')) {
      const browserName = launchOptions.channel ?? config.browser.browserName;
      throw new Error(`Missing system dependencies required to run browser ${browserName}. Install them with: sudo npx playwright install-deps ${browserName}`);
    }
    if (error.message.includes('ProcessSingleton') || error.message.includes('exitCode=21'))
      throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
    throw error;
  }
}

async function createUserDataDir(config: FullConfig, clientInfo: ClientInfo) {
  const dir = process.env.PWMCP_PROFILES_DIR_FOR_TEST ?? path.join(defaultCacheDirectory(), 'ms-playwright-mcp');
  const browserToken = config.browser.launchOptions?.channel ?? config.browser?.browserName;
  // Hesitant putting hundreds of files into the user's workspace, so using it for hashing instead.
  const rootPathToken = createHash(clientInfo.cwd);
  const result = path.join(dir, `mcp-${browserToken}-${rootPathToken}`);
  await fs.promises.mkdir(result, { recursive: true });
  return result;
}

function createHash(data: string): string {

View on GitHub (pinned to c8fc3bf8d3)

Solutions

Run `sudo npx playwright install-deps <browserName>` (or `chromium`/`firefox`/`webkit`) to install OS libraries.
Use a Playwright-provided Docker base image that already includes the deps.
If `sudo` is unavailable, install the listed packages via the distro package manager, or use `apt-get` inside the container Dockerfile.

Example fix

# before
playwright mcp   # launch fails: cannot open shared object file
# after
sudo npx playwright install-deps chromium
playwright mcp

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await launchPersistent(opts);
} catch (e) {
  if (/Missing system dependencies/.test((e as Error).message)) {
    console.error('Install deps, then retry: sudo npx playwright install-deps <browser>');
    process.exit(2);
  }
  throw e;
}

Prevention

Run `npx playwright install-deps` on fresh Linux hosts/containers.
Use a Playwright base Docker image with deps preinstalled.
Bake the install-deps step into your Dockerfile/CI setup script.

When it happens

Trigger: Launching Chromium/Firefox/WebKit on a Linux system (container, minimal VM, CI image) where the OS-level libraries the browser links against are not installed. The browser process fails to load a `.so` and Playwright surfaces that as the launch error.

Common situations: Running the browser for the first time on a slim Docker image (alpine-debian, distroless); CI image that installed the browser but not its OS deps; a system upgrade removed a required library; switching to a channel (e.g. `chrome`) that needs different libs than the bundled Chromium.

Related errors

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