It will not run
libnss3.so: cannot open shared object file
An error naming a specific .so file that does not exist. libnss3 is the most common, followed by libatk-bridge and libgbm, and fixing one reveals the next.
What is actually happening
This is the previous error with the first missing library named. It appears one library at a time because the loader stops at the first failure, which makes fixing it an iterative process rather than a single change.
Confirming it is this and not something that looks like it
Run ldd against the browser binary inside the container. It lists every missing library at once instead of one per attempt.
The fix
Install the full dependency set rather than adding libraries one at a time. Adding them individually will take several build cycles and you will still be missing one the first time a document uses a feature you did not test.
# Everything missing, in one pass, instead of one rebuild per library.
ldd /root/.cache/puppeteer/chrome/*/chrome-linux64/chrome | grep "not found"If that was not it
These produce the same symptom often enough to be worth ruling out before assuming the fix above did not work.
- libgbm1, needed even in headless mode on many builds
- No fonts installed at all, which does not error but renders everything as boxes
- A distroless base image, which cannot install packages by design
- A multi-stage build where the libraries were installed in the build stage and not the runtime stage
Frequently asked
Does this happen with every rendering engine?
The behaviour behind it is not specific to one tool. This is the previous error with the first missing library named. Anything rendering HTML to a paged medium has to make the same decision, so the fix travels with you if you change how the render happens.
Will this show up as an error in my logs?
Yes, this one surfaces as a thrown error or a failed status, which is why it is at least findable. The harder half is that the message often names the call that was in flight rather than the thing that actually failed.
Related failures
Problems people arrive at from the same starting point, or mistake for this one.
Failed to launch the browser process
A headless browser is not a self-contained binary.
Navigation timeout of 30000 ms exceeded
The default wait condition is the network going idle, and something on the page is keeping it busy: an analytics beacon, a font request to a host that is not responding, a polling request, or an ad script.
Protocol error (Page.printToPDF): Target closed
The tab crashed, and by far the most common reason is memory.
Chromium does not fit in an AWS Lambda deployment package
A full browser build is several hundred megabytes and the unzipped package limit is 250MB.
PDF generation runs out of memory
Two multiplying factors.
CSS for paged documents, and what actually works
Which parts of the paged media specification a browser-based render implements.
Everything that goes wrong, by category
The full list, grouped by where in the pipeline it breaks.
Paste your markup and see the rendered document, without signing up.