microsoft/playwright · critical · Error

Failed to launch the browser process.\nBrowser logs:\n

Error message

Failed to launch the browser process.\nBrowser logs:\n${updatedLog}

What it means

Thrown in _launchProcess after the browser process exits (exitPromise.isDone()) before the ready-state/websocket endpoint is reached. The message embeds rewritten browser logs (doRewriteStartupLog) so the developer can see the actual stderr that caused the crash.

Solutions

1. Read the embedded browser logs in the error message first — they name the real cause (e.g. 'error while loading shared libraries').
2. Install OS dependencies: 'npx playwright install-deps' (Linux).
3. Reinstall the browser: 'npx playwright install <browser>'.
4. If running as root in a container, ensure the bundled args include --no-sandbox or use the official Playwright Docker image.
5. On Apple Silicon, install the matching architecture browser build.

Example fix

// before (fails on minimal Linux)
const b = await chromium.launch();
// after
// shell:
//   npx playwright install-deps chromium
//   npx playwright install chromium
const b = await chromium.launch();

import fs from 'fs';
// Pre-flight OS check (Linux): ensure deps installable
async function preflightLaunch() {
  if (process.platform === 'linux') {
    // recommend running install-deps; cannot fully validate here
  }
}

try {
  browser = await chromium.launch();
} catch (e) {
  const msg = String(e.message || e);
  if (msg.includes('Failed to launch the browser process')) {
    // parse embedded Browser logs; surface actionable hint
    throw new Error('Browser failed to start. Run: npx playwright install-deps && npx playwright install chromium. Logs:\n' + msg);
  }
  throw e;
}

When it happens

Trigger: chromium.launch/firefox.launch/webkit.launch where the process starts then immediately exits — missing shared libraries, sandbox issues, wrong architecture, headless on a display-less host without the right flags, or a corrupted binary.

Common situations: Running headless Chromium on a minimal Linux/CI image without 'npx playwright install-deps'. Browser upgraded but system libs not. Apple Silicon running an x64 build under Rosetta failures. Container running as root without --no-sandbox (Playwright usually adds this, but custom args can override).

Related errors

• Cannot launch Firefox with relative home directory. Did you…
• Failed to launch because executable doesn't exist at
• Unsupported channel
• An active lockfile is found at
• Arguments can not specify page to be opened

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

Appendix: source

Thrown at packages/playwright-core/src/server/browserType.ts:272

      } finally {
        clearTimeout(timer!);
      }
    }
    browserProcess = {
      onclose: undefined,
      process: launchedProcess,
      close: () => closeOrKill((options as any).__testHookBrowserCloseTimeout || DEFAULT_PLAYWRIGHT_TIMEOUT),
      kill
    };
    try {
      const { wsEndpoint } = await progress.race([
        this.waitForReadyState(options, browserLogsCollector),
        exitPromise.then(() => ({ wsEndpoint: undefined })),
      ]);
      if (exitPromise.isDone()) {
        const log = helper.formatBrowserLogs(browserLogsCollector.recentLogs());
        const updatedLog = this.doRewriteStartupLog(log);
        throw new Error(`Failed to launch the browser process.\nBrowser logs:\n${updatedLog}`);
      }
      if (!this.supportsPipeTransport(options)) {
        transport = await WebSocketTransport.connect(progress, wsEndpoint!);
      } else {
        const stdio = launchedProcess.stdio as unknown as [NodeJS.ReadableStream, NodeJS.WritableStream, NodeJS.WritableStream, NodeJS.WritableStream, NodeJS.ReadableStream];
        transport = new PipeTransport(stdio[3], stdio[4]);
      }
      return { browserProcess, artifactsDir: prepared.artifactsDir, userDataDir: prepared.userDataDir, transport, wsEndpoint };
    } catch (error) {
      await progress.race(closeOrKill(DEFAULT_PLAYWRIGHT_TIMEOUT).catch(() => {}));
      throw error;
    }
  }

  async connectOverCDP(progress: Progress, params: channels.BrowserTypeConnectOverCDPParams): Promise<Browser> {
    throw new Error('CDP connections are only supported by Chromium');
  }

View on GitHub (pinned to c8fc3bf8d3)