Playwright "error while loading shared libraries: libnss3.so" in CI

By Kaveh Alemi·Latchkey

The Chromium binary exists and starts, but ld.so cannot resolve libnss3.so because the package providing it (libnss3) is not installed. This is the single most common missing library on minimal Debian/Ubuntu images.

What this error means

A launch fails with "browserType.launch: ... error while loading shared libraries: libnss3.so: cannot open shared object file: No such file or directory", often the only missing library on an otherwise working image.

playwright

browserType.launch: Target page, context or browser has been closed
Browser logs:
<launching> .../headless_shell ... error while loading shared libraries:
libnss3.so: cannot open shared object file: No such file or directory

Diagnose it: browser, server, or timing?

End-to-end failures in CI are dominated by three causes that have nothing to do with the test: the browser binary is missing, the application under test is not listening yet, or the test raced the page. Establish which before reading the assertion.

Terminal

# 1. are the browsers actually installed in THIS job?
npx playwright install --with-deps chromium
npx playwright --version

# 2. is the app up before the tests start?
npx wait-on http://localhost:3000 --timeout 60000

# 3. capture evidence for the failure you cannot reproduce
npx playwright test --trace on --video retain-on-failure

Common causes

libnss3 not installed in the container

Chromium dynamically links Network Security Services; a minimal image omits libnss3, so the loader cannot start the browser.

Only some Playwright dependencies were installed

A hand-picked apt list missed libnss3, whereas playwright install-deps would have included it.

How to fix it

Let Playwright install the full dependency set

Run install-deps (or install --with-deps) so every required library, including libnss3, is present.

Terminal

npx playwright install-deps chromium

Install the package directly if you manage apt yourself

When you control the Dockerfile, add libnss3 explicitly alongside the other browser libraries.

Dockerfile

apt-get update && apt-get install -y \
  libnss3 libatk-bridge2.0-0 libgbm1 libasound2

Make the browser cache safe

Key the browser cache to the exact test-runner version. A cache restored from a different version gives you a binary that does not match the client and fails in a way that reads like a missing install.
Install browsers after dependencies, not before; a dependency install can replace the package that owns the browser path.
Prefer the vendor container image when the runner allows it. It removes the whole class of missing-system-library failures.

How to prevent it

Prefer playwright install-deps over a manual apt allowlist.
Build a custom image once with all browser libraries baked in.
Test the image by launching a browser in a smoke step before the full suite.

Frequently asked questions

What causes Playwright "error while loading shared libraries: libnss3.so" in CI?

There are 2 common causes: libnss3 not installed in the container and only some playwright dependencies were installed. Chromium dynamically links Network Security Services; a minimal image omits libnss3, so the loader cannot start the browser.

How do I fix Playwright "error while loading shared libraries: libnss3.so" in CI?

There are 2 fixes depending on which cause you have: let playwright install the full dependency set and install the package directly if you manage apt yourself. Work through them in order, since the first is the most common.

What does Playwright "error while loading shared libraries: libnss3.so" in CI actually mean?

A launch fails with "browserType.launch: ...

How do I stop Playwright "error while loading shared libraries: libnss3.so" in CI happening again?

Prefer playwright install-deps over a manual apt allowlist. The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation