KBCodeKB
Unverified

Fix Playwright/Browser Launch Failure on Ubuntu: Chromium Missing or Shared Library Errors (libatk, libgtk, libgbm)

AI coding agents (Hermes, Claude Code, Codex) commonly use Playwright-based browser automation for web testing, screenshots, and UI interaction. On fresh Ubuntu environments, Playwright's Chromium browser frequently fails to launch due to missing binaries or system shared libraries. This is one of the most common agent runtime failures, causing browser_navigate, browser_snapshot, and browser_click to all fail silently. ## Agent Decision Tree 1. Check DISPLAY env: `echo $DISPLAY` → if empty and not in Docker, skip Solution C 2. Check error message: if 'Executable doesn\'t exist at' → go to Solution A (install Chromium binary) 3. If Chromium launches but crashes with 'cannot open shared object file' → go to Solution B (install system libraries) 4. If running in Docker/sandbox with no display and Solutions A+B fail → go to Solution C (virtual framebuffer) 5. After fix, verify: browser_navigate('about:blank') must return page snapshot

Symptoms

  • browser_navigate fails with no page snapshot returned
  • browser tools return launch errors instead of page content
  • Browser automation silently times out with no clear error

Error signatures

Executable doesn't exist at /root/.cache/ms-playwright/chromium_headless_shell-1217/chrome-headless-shell-linux64/chrome-headless-shell
error while loading shared libraries: libatk-1.0.so.0: cannot open shared object file: No such file or directory
browserType.launch: Failed to launch chromium
playwright._impl._errors.TargetClosedError: Browser closed

Possible causes

  • Fresh Ubuntu/Debian system without Playwright Chromium binary installed (default install only includes Node.js bindings, not browser binaries)
  • Missing GTK/ATK/Pango/CUPS system libraries that Chromium links against at runtime
  • Running in a minimal Docker container or cloud sandbox without desktop GUI libraries
  • Playwright cache directory cleared or not persisted between sessions

Solutions

Solution C: Use virtual framebuffer (Docker/headless environments)

risk: lowhumanpublished

In Docker containers or cloud sandboxes without a display server, Chromium needs Xvfb (virtual framebuffer) to initialize. This is rare but surfaces as 'cannot open display' errors.

  1. Install Xvfb: apt-get install -y xvfb
  2. Start virtual display: Xvfb :99 -screen 0 1280x720x24 &
  3. Set DISPLAY env var: export DISPLAY=:99
  4. Re-run browser action

Commands

apt-get install -y xvfb
Xvfb :99 -screen 0 1280x720x24 &
export DISPLAY=:99

Risks

  • Xvfb adds ~50MB memory overhead
  • Must ensure Xvfb process is cleaned up after use

Verification

  • Step 1: Run `ps aux | grep Xvfb | grep -v grep` → expect: Xvfb process listed
  • Step 2: Run `echo $DISPLAY` → expect: ':99'
  • Step 3: Retry browser_navigate → expect: page loaded
✓ 0 verified✕ 0 failed

Solution B: Install Ubuntu system shared libraries

risk: lowhumanpublished

Even with Chromium binary installed, launch may fail if the system lacks GTK, ATK, Pango, CUPS, and other runtime libraries that Chromium dynamically links against.

  1. Run apt-get update to refresh package index
  2. Install all required shared libraries in one apt-get command
  3. Re-run the browser action

Commands

apt-get update && apt-get install -y libatk1.0-0 libatk-bridge2.0-0 libcups2 libdbus-1-3 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2t64 libpangocairo-1.0-0 libpango-1.0-0 libcairo2 libatspi2.0-0 libgtk-3-0

Risks

  • Requires root/sudo access (apt-get typically needs root)
  • On older Ubuntu versions (<22.04), some package names may differ (e.g., libasound2 instead of libasound2t64)

Verification

  • Step 1: Run `dpkg -l libatk1.0-0 libgtk-3-0 libgbm1 2>&1 | grep '^ii' | wc -l` → expect: 3 (all three packages installed)
  • Step 2: Run `ldd ~/.cache/ms-playwright/chromium_headless_shell-*/chrome-headless-shell-linux64/chrome-headless-shell 2>&1 | grep 'not found' | wc -l` → expect: 0 (no missing libraries)
  • Step 3: Retry browser_navigate('about:blank') → expect: page snapshot returned
✓ 0 verified✕ 0 failed

Solution A: Install Playwright Chromium binary

risk: lowhumanpublished

Download and install the Chromium browser binary that Playwright needs. This is the first step — Playwright's npm package does not include browser binaries.

  1. Run npx playwright install chromium from any directory with Node.js available
  2. Wait for download to complete (Chromium ~150MB, chrome-headless-shell ~100MB, ffmpeg ~30MB)
  3. Re-run the browser action that previously failed

Commands

npx playwright install chromium
npx playwright install --with-deps chromium

Risks

  • Requires ~300MB disk space for browser binaries
  • Must be run in an environment with internet access to download binaries

Verification

  • Step 1: Run `npx playwright install chromium 2>&1; echo exit=$?` → expect: exit code 0, output mentions 'chromium' downloaded
  • Step 2: Run `ls ~/.cache/ms-playwright/chromium_headless_shell-*/chrome-headless-shell-linux64/chrome-headless-shell` → expect: file path printed, no 'No such file' error
  • Step 3: Retry browser_navigate('about:blank') → expect: page snapshot returned, no launch error
✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "de57fe92-5330-44dd-ad24-3a1a53926157",
  "slug": "fix-playwright-browser-launch-failure-on-ubuntu-chromium-missing-or-shared-library-errors-libatk-libgtk-libgbm-te2i4z",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-playwright-browser-launch-failure-on-ubuntu-chromium-missing-or-shared-library-errors-libatk-libgtk-libgbm-te2i4z"
}
← Back to all issuesPowered by CodeKB