{"record":{"id":"ee7d5410769c3b28","repo":"microsoft/playwright","slug":"missing-system-dependencies-required-to-run-browse","errorCode":null,"errorMessage":"Missing system dependencies required to run browser ${browserName}. Install them with: sudo npx playwright install-deps ${browserName}","messagePattern":"Missing system dependencies required to run browser (.+?)\\. Install them with: sudo npx playwright install-deps (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/playwright-core/src/tools/mcp/browserFactory.ts","lineNumber":189,"sourceCode":"    ...config.browser.contextOptions,\n    handleSIGINT: false,\n    handleSIGTERM: false,\n    ignoreDefaultArgs: configIgnoreDefaultArgs === true\n      ? true\n      : [\n        '--disable-extensions',\n        ...Array.isArray(configIgnoreDefaultArgs) ? configIgnoreDefaultArgs : [],\n      ],\n  };\n  try {\n    const browserContext = await browserType.launchPersistentContext(userDataDir, launchOptions);\n    const browser = browserContext.browser()!;\n    return browser;\n  } catch (error: any) {\n    throwIfExecutableMissing(error, config);\n    if (error.message.includes('cannot open shared object file: No such file or directory')) {\n      const browserName = launchOptions.channel ?? config.browser.browserName;\n      throw new Error(`Missing system dependencies required to run browser ${browserName}. Install them with: sudo npx playwright install-deps ${browserName}`);\n    }\n    if (error.message.includes('ProcessSingleton') || error.message.includes('exitCode=21'))\n      throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);\n    throw error;\n  }\n}\n\nasync function createUserDataDir(config: FullConfig, clientInfo: ClientInfo) {\n  const dir = process.env.PWMCP_PROFILES_DIR_FOR_TEST ?? path.join(defaultCacheDirectory(), 'ms-playwright-mcp');\n  const browserToken = config.browser.launchOptions?.channel ?? config.browser?.browserName;\n  // Hesitant putting hundreds of files into the user's workspace, so using it for hashing instead.\n  const rootPathToken = createHash(clientInfo.cwd);\n  const result = path.join(dir, `mcp-${browserToken}-${rootPathToken}`);\n  await fs.promises.mkdir(result, { recursive: true });\n  return result;\n}\n\nfunction createHash(data: string): string {","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/microsoft/playwright/blob/c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6/packages/playwright-core/src/tools/mcp/browserFactory.ts#L171-L207","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nplaywright mcp   # launch fails: cannot open shared object file\n# after\nsudo npx playwright install-deps chromium\nplaywright mcp","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await launchPersistent(opts);\n} catch (e) {\n  if (/Missing system dependencies/.test((e as Error).message)) {\n    console.error('Install deps, then retry: sudo npx playwright install-deps <browser>');\n    process.exit(2);\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["browser-launch","linux","system-dependencies","shared-libraries","install"],"backgroundTag":null,"analyzedSha":"c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6","analyzedAt":"2026-08-12T07:26:36.950Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}