firebase deploy cannot load the .env file in the functions folder
FirebaseError: Failed to load environment variables from .envShort answer
The CLI reads .env files from the functions folder at deploy time and rejects ones it cannot use. The usual causes are a reserved key such as a FIREBASE_ or X_GOOGLE_ name, files saved in the wrong folder or under the wrong name, and lines that are not in KEY=value form.
Fix it fast
1Find out which cause you have
List every dotenv file the CLI would pick up, and print only the key names so you can read them without exposing values.
cut -d= -f1 functions/.env functions/.env.* 2>/dev/null2Match what you see, then jump to its fix
- 1
The key list shows a name starting with FIREBASE_, X_GOOGLE_ or EXT_, or a name like PORT or GCLOUD_PROJECTA key uses a reserved nameFix - 2
The first-step command prints nothing, or the file sits in the project rootThe file is in the wrong folder or has the wrong nameFix - 3
The key list shows a line with no equals sign, or a value cut off at a # characterA line is not valid dotenv syntaxFix
- 1
What does the error look like?
FirebaseError: Failed to load environment variables from .env
Cause 1 of 3
A key uses a reserved name
1Check
These prefixes and a fixed set of names (including PORT, K_SERVICE, GCP_PROJECT, GCLOUD_PROJECT, FUNCTION_TARGET) are reserved for the platform.
grep -nE '^(FIREBASE_|X_GOOGLE_|EXT_|PORT=|GCP_PROJECT=|GCLOUD_PROJECT=)' functions/.env*2Fix
Rename the key to something that is yours, for example APP_PORT or MY_FIREBASE_ENV, and change the code that reads it.
# functions/.env
APP_PORT=80803Verify
Deploy again.
firebase deploy --only functionsConfirmed by firebase.google.com
Cause 2 of 3
The file is in the wrong folder or has the wrong name
1Check
The CLI loads .env and .env.<project_ID> (or .env.<alias>) from the functions directory. .env.local is for the emulator only.
firebase use
ls -a functions | grep '^\.env'2Fix
Move the file into the functions folder and name it after the project ID or alias you deploy to.
mv .env functions/.env.my-project-id3Verify
Deploy to that project.
firebase deploy --only functions --project my-project-idConfirmed by firebase.google.com
Cause 3 of 3
A line is not valid dotenv syntax
1Check
The files use the dotenv format: KEY=value lines. In that format a # in an unquoted value starts a comment, and lines that are not KEY=VALUE are not loaded.
grep -nv '^[A-Za-z_][A-Za-z0-9_]*=' functions/.env | grep -v '^[0-9]*:\s*\(#\|$\)'2Fix
Put one KEY=value per line, and wrap any value that contains # in quotes.
API_URL=https://example.com/path
PASSWORD_HINT="starts with #1"3Verify
Re-run the check; it prints nothing, then deploy.
firebase deploy --only functionsConfirmed by github.com
How do I stop it coming back?
- Keep secrets in Secret Manager with firebase functions:secrets:set instead of .env files.
- Prefix your own keys with the app name so they never meet a reserved name.
- Name files after the project ID and commit only the non-sensitive ones.
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
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 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 fixBack end
Firebase Functions fails to load because csv-parse/sync is missing
Cannot find module 'csv-parse'
Firebase installs only what the functions package.json lists under dependencies, and it ignores your local node_modules at deploy.
3 causes, each with a fixBack end
firebase deploy rejects the Node.js version in a Cloud Functions package.json
`runtime` field is required but was not found in firebase.json or package.json.
The Firebase CLI builds the runtime name straight from engines.node in package.json, so the value must be a plain version such as 22, and a version that Google has decommissioned is refused.
5 causes, each with a fix