Puppeteer Tutorial | Fixing Common Errors while installing Puppeteer

Puppeteer is a popular js based Node module that lets you interact with Chromium in a headless manner. It can help your Node js and Javascript based application scrape content from the web or, screenshot pages, in a predictable and reliable way. If you are reading this, chances are you are stuck with an error in the headless chromium installation of Puppeteer which appears to be too common. The goal of this puppeteer tutorial is to fix them and install puppeteer without any errors.

General rule of thumb solution

Check Node version, Chromium version and Puppeteer version. Downgrade all or, any if that helps. Often, there are bugs and only way to deal with is to upgrade or downgrade to move to a more stable version.

To solve puppeteer installation errors, there are a lot of solutions, but we are sharing only the ones we tried and tested. So they are 100% confirmed to work, at least, in our testing environment, which is Ubuntu, but we can't confirm about yours.

Having errors while running Puppeteer?

Seems like you are not facing this problem alone, others too have faced it and while there's no elegant solution to it presently, we will walk you through a couple of solutions we tested, and it worked in our development environment.

Headless chrome(-ium) needs a lot of dependencies to work with, and puppeteer doesn't install them all.

Puppeteer installation is quite tricky and assumes you have all the .so library files that Chromium needs. This is specifically a problem with puppeteer and not pupeteer-core, as puppeteer comes with the chromium. It's not properly documented in the Puppeteer documentation, and hence a cause of confusion for many developers working on browser automation with puppeteer.

If you see an error like , Failed to launch chrome, it's likely a problem in chromium rather than puppeteer.

Installing Puppeteer

Using npm:

Run npm install puppeteer for the whole setup consisting of chromium, or, just npm install puppeteer-core for only puppeteer's core functionality or, just the puppeteer module, which is suitable if Chromium installation has already been dealt with or, the app is running it remotely on another container/instance.

Troubleshoot common errors in Puppeteer

Case 1: Missing dependencies and libraries

Firstly, get a list of missing dependencies in the local chromium installation using the ldd command -

ldd chrome | grep not | awk '{print $1}' | awk -F '.so' '{print $1}' | tr '\n' ' '

This command needs to be run in the directory where chromium is installed by puppeteer, which in our case happens to be ~/ss/node_modules/puppeteer/.local-chromium/linux-848005/chrome-linux, but the linux-848005 part and ~/ss/ path might vary. So that needs to be taken care of, the exact path can be easily found by cd-ing into this path, however - /node_modules/puppeteer/.local-chromium/. It would give back the names of the files not found but are required by Chromium thus giving a hint of the missing dependencies in the installation, by extracting them out with grep, tr and awk (which are usually pre-installed in most Linux distros)

Typically, these components are missing in Debian,

libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget libgbm-dev

One can install them by this command,

sudo apt-get install -y libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget libgbm-dev

Solution: Install all the missing dependencies.

Once that's done, puppeteer is ready to be run, without those pesky errors!

Case 2: Running Chromium as root (SECURITY ALERT!)

You could get errors like running as root without --no-sandbox is not supported puppeteer

The second issue is a way to prevent security issues, and can be disabled by following the below steps –

If this error pops up in the logs, it means Puppeteer is being run as 'root' user, which is bad from the security perspective. It's advisable to be run in a sandboxed environment so, in case of a hack, an attacker can't do much damage. It can be dangerous if Chromium is being run on a production machine running the main application, if that's the case - stop now and rethink!

Running as root without --no-sandbox is not supported.

Chromium, by default, doesn't allow to run itself as root as a security precaution, so that vulnerabilities in Chromium don't allow privilege escalation through bugs like RCE, which aren't too uncommon. While this is discouraged, but if one still wishes to take the risk, and run as root on a sandbox container, it can be done by passing the --no-sandbox flag as arguments to pupeeter.launch() method

const puppeteer = require('puppeteer');

(async () => {
	const browser = await puppeteer.launch(
    {args: ['--no-sandbox']},
    );
    console.info(browser);
    await browser.close();
})(); 

Solution: Pass the --no-sandbox flag while launching chromium instance through args

Case 3: Puppeteer timeout errors

Puppeteer TimeoutError: Navigation timeout of 30000 ms exceeded is a common error which appears when the page contains some large assets that can consume a lot of resources, and need some time to load. If the page load time is huge, the performance can take a hit. One can include the code in a try-catch block to handle this error better, but in general a maximum timeout needs to be set, so that puppeteer doesn't get stuck on a particular page for too long.

For example, adding the following bit of code, would set the default timeout to 5,000 ms or, 5 s. But if the page loads some large resources (like video content), it's advisable to increase it to 10,000 ms or, 10 s at most.

await page.setDefaultNavigationTimeout(5000);

Solution: Set a custom page timeout.

That's it...

A list of Puppeteer API methods can be found here, which is a good resource to get started with puppeteer.

Didn't work? We'll help you free-of-cost

Was this useful? Say us thanks? and if not, we would like to know what issues you are facing, shoot us a mail, team [@] savebreach.com, if the issues are small we will help you solve it, and also include them in our blog. Let's connect :)

When asking for help: send us the environment you are running the software on, the specific configuration, a small stack trace with sensitive information removed, and wait for at least 3 business days for a response.