Maaz Zindani

Loading the index…

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

Puppeteer cannot find the browser after deploying to Firebase Functions

ErrorCould not find expected browser locally

Short answer

Puppeteer downloads Chrome to ~/.cache/puppeteer at install time. Cloud Functions caches node_modules between builds and may skip that step, so the browser is missing at runtime. Set cacheDirectory to a folder inside node_modules, reinstall, and redeploy. Also check that install scripts are not blocked.

  • Applies to Puppeteer 24, Node.js 22, firebase-tools 14, Cloud Functions for Firebase 2nd gen
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the deployed function's logs and note the browser path in the error message. The path shows which cache folder Puppeteer looked in.

    firebase functions:log
  2. 2Match what you see, then jump to its fix

    1. 1The path in the error starts with the home folder, under .cache/puppeteerThe browser cache sits outside node_modulesFix
    2. 2ls on the cache folder shows no chrome directory even after npm installThe install script that downloads Chrome did not runFix
    3. 3The browser exists on disk, but the path in the error differs from where you installed itThe cache folder was set at install but not at run timeFix

What does the error look like?

  • Could not find expected browser locally
  • Could not find Chromium

Cause 1 of 3

The browser cache sits outside node_modules

1Check

The default cache is ~/.cache/puppeteer. On Cloud Functions the build keeps node_modules between builds and may skip Puppeteer's postinstall step, so a browser stored outside it can be absent at runtime.

ls ~/.cache/puppeteer

2Fix

Add a Puppeteer config file in the functions folder that puts the cache under node_modules, then reinstall so the browser is downloaded there.

// functions/.puppeteerrc.cjs
const { join } = require('path');
module.exports = {
  cacheDirectory: join(__dirname, 'node_modules', '.puppeteer_cache'),
};

# then
cd functions && rm -rf node_modules && npm install

3Verify

The error is gone, or its path now points inside node_modules; redeploy and call the function.

firebase deploy --only functions

Confirmed by pptr.dev

Did this fix it?

Cause 2 of 3

The install script that downloads Chrome did not run

1Check

Package managers that block install scripts skip the automatic download. Check whether your manager or CI blocks lifecycle scripts.

ls node_modules/.puppeteer_cache ~/.cache/puppeteer

2Fix

Run the browser install explicitly, or allow the Puppeteer postinstall script.

npx puppeteer browsers install

3Verify

The cache folder now holds a chrome directory.

ls ~/.cache/puppeteer

Confirmed by pptr.dev

Did this fix it?

Cause 3 of 3

The cache folder was set at install but not at run time

1Check

If you used the PUPPETEER_CACHE_DIR variable only for the install command, the launch looks in the default folder.

echo $PUPPETEER_CACHE_DIR

2Fix

Stop relying on the variable. Put cacheDirectory in the config file, which Puppeteer reads at both times.

// .puppeteerrc.cjs
module.exports = { cacheDirectory: require('path').join(__dirname, 'node_modules', '.puppeteer_cache') };

3Verify

Reinstall, redeploy and call the function again.

cd functions && npm install && cd .. && firebase deploy --only functions

Confirmed by pptr.dev

Did this fix it?

How do I stop it coming back?

  • Keep the Puppeteer config file in version control next to package.json.
  • After a Puppeteer upgrade, delete node_modules and reinstall so the matching browser is downloaded.

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

Back end

firebase-admin warns that FIREBASE_CONFIG is missing

Warning, FIREBASE_CONFIG environment variable is missing. Initializing firebase-admin will fail

Cloud Functions for Firebase sets FIREBASE_CONFIG for you; a script run with plain node does not have it.

3 causes, each with a fix

Next step

Want this handled for good?

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