Puppeteer cannot find the browser after deploying to Firebase Functions
Could not find expected browser locallyShort 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.
Fix it fast
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:log2Match what you see, then jump to its fix
- 1
The path in the error starts with the home folder, under .cache/puppeteerThe browser cache sits outside node_modulesFix - 2
ls on the cache folder shows no chrome directory even after npm installThe install script that downloads Chrome did not runFix - 3
The 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
- 1
What does the error look like?
Could not find expected browser locallyCould 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/puppeteer2Fix
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 install3Verify
The error is gone, or its path now points inside node_modules; redeploy and call the function.
firebase deploy --only functionsConfirmed by pptr.dev
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/puppeteer2Fix
Run the browser install explicitly, or allow the Puppeteer postinstall script.
npx puppeteer browsers install3Verify
The cache folder now holds a chrome directory.
ls ~/.cache/puppeteerConfirmed by pptr.dev
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_DIR2Fix
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 functionsConfirmed by pptr.dev
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:
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Back end
Puppeteer cannot start Chrome on a Linux server
error while loading shared libraries: libnss3.so: cannot open shared object file
Puppeteer prints the real reason below the first line, so read that.
4 causes, each with a fixBack end
Firebase Cloud Functions respond slowly, especially on the first call
Every function in the project is slow after deploy, even tiny ones
Most slow first calls are cold starts: the runtime starts from scratch, loads your code and runs global-scope work before it can answer.
3 causes, each with a fixBack 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 fixBack end
firebase deploy --only functions fails with a generic deploy error
HTTP 429
The generic message hides a specific one.
3 causes, each with a fixBack end
firebase deploy cannot load the .env file in the functions folder
FirebaseError: Failed to load environment variables from .env
The CLI reads .env files from the functions folder at deploy time and rejects ones it cannot use.
3 causes, each with a fixBack end
firebase deploy cannot load your functions: user code failed to load
Functions codebase could not be analyzed successfully. It may have a syntax or runtime error
The Firebase CLI loads your functions code on your machine before it deploys, to learn which functions exist.
4 causes, each with a fix