Headless Browser "error while loading shared libraries" in CI

By Daniel Zoghalchali·Latchkey

A headless browser binary exists but cannot start because the Linux shared libraries it links against - libnss3, libatk, libgbm, libasound, fonts - are missing from the slim CI container image.

What this error means

The browser fails to launch with "error while loading shared libraries: libnss3.so: cannot open shared object file," regardless of which runner (Playwright, Puppeteer, Selenium, Karma) drives it.

/root/.cache/.../chrome: error while loading shared libraries:
libnss3.so: cannot open shared object file: No such file or directory

Common causes

Slim base image without browser libraries

Minimal images (alpine, debian-slim, distroless) omit the X/graphics/audio/font libraries Chromium and Firefox need, so the binary cannot load.

Browser installed without its OS deps

The browser was downloaded by the test tool, but no step installed the matching system packages (install-deps, apt packages).

How to fix it

Install the required system libraries

apt-get update && apt-get install -y \
  libnss3 libatk1.0-0 libatk-bridge2.0-0 libgbm1 \
  libasound2 libxkbcommon0 fonts-liberation

Or use a browser-ready image

# Playwright, Cypress, and Selenium publish full images with deps
container: mcr.microsoft.com/playwright:v1.49.0-jammy

How to prevent it

• Use the tool's official browser-ready image in CI.
• If using a slim image, install browser deps in the build, not per-run.
• Pin the image so libraries match the browser version.

Frequently asked questions

Related guides

References

• GitHub Actions documentation