microsoft/playwright · critical · Error

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

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.

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)

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
• Unsupported ${this._name} channel "${options.channel}"
• Failed to launch ${this._name} because executable doesn't ex
• Arguments can not specify page to be opened
• Server is already started.

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