Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Puppeteer installed but cannot find its Chrome download

ErrorCould not find Chrome (ver. ...)

Short answer

Puppeteer looks for its browser in a cache folder, ~/.cache/puppeteer by default. The error means that folder has no matching Chrome: the install script was blocked, the browser was never downloaded, or the app runs with another home directory or cache path than the install did. Install the browser again, or pin one cache folder.

  • Applies to Puppeteer (current release), Node.js 22, Node.js 24, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the browsers Puppeteer has in its cache. An empty or missing folder points at the first cause.

    ls ~/.cache/puppeteer
  2. 2Match what you see, then jump to its fix

    1. 1npm install finished with no download message, and the cache folder is emptyThe package manager blocked the install scriptFix
    2. 2It works in your shell and fails under a service, a container user or a deploy stepThe app runs as another user or with another home folder than the installFix
    3. 3Works after a local install, then fails on Google App Engine or Cloud FunctionsThe platform keeps node_modules between builds but not the cacheFix

What does the error look like?

  • Could not find Chrome (ver. ...)
  • Could not find expected browser locally

Cause 1 of 3

The package manager blocked the install script

1Check

If your package manager blocks install scripts, the browser is not downloaded and the error follows.

ls ~/.cache/puppeteer/chrome 2>/dev/null || echo missing

2Fix

Download the browser by hand, or allow the Puppeteer install script in package.json for npm.

npx puppeteer browsers install

# or allow the script in package.json
"allowScripts": { "puppeteer": true }

3Verify

The cache folder now has a chrome entry.

ls ~/.cache/puppeteer/chrome

Confirmed by pptr.dev

Did this fix it?

Cause 2 of 3

The app runs as another user or with another home folder than the install

1Check

Since version 19 Puppeteer keeps browsers in a cache under the home directory by default. Another user or home gets another, empty cache.

echo "$HOME"
ls "$HOME/.cache/puppeteer"

2Fix

Pin the cache folder in .puppeteerrc.cjs inside the project, then reinstall so the browser lands there.

// .puppeteerrc.cjs
const { join } = require('path');

module.exports = {
  cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
};

3Verify

Reinstall and check the project folder.

npm install puppeteer
ls .cache/puppeteer

Confirmed by pptr.dev

Did this fix it?

Cause 3 of 3

The platform keeps node_modules between builds but not the cache

1Check

On those platforms the Puppeteer docs say only node_modules is cached between builds, so a browser in the default cache folder is gone at run time.

ls node_modules/.puppeteer_cache

2Fix

Point the cache folder inside node_modules, as the troubleshooting guide shows, and reinstall.

// .puppeteerrc.cjs
const { join } = require('path');

module.exports = {
  cacheDirectory: join(__dirname, 'node_modules', '.puppeteer_cache'),
};

3Verify

Install again, then check that the browser sits under node_modules.

npm install && ls node_modules/.puppeteer_cache

Confirmed by pptr.dev

Did this fix it?

How do I stop it coming back?

  • Run the browser install as part of the build, and fail the build if the cache folder is empty.
  • Keep the cache folder in the project when the runtime user differs from the build user.
  • Pin the Puppeteer version so the browser version it wants does not change under you.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.