Maaz Zindani

Loading the index…

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

firebase deploy cannot load the .env file in the functions folder

ErrorFirebaseError: Failed to load environment variables from .env

Short 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.

  • Applies to firebase-tools 14, Node.js 22, firebase-functions 6
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/null
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 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. 3The key list shows a line with no equals sign, or a value cut off at a # characterA line is not valid dotenv syntaxFix

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=8080

3Verify

Deploy again.

firebase deploy --only functions

Confirmed by firebase.google.com

Did this fix it?

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-id

3Verify

Deploy to that project.

firebase deploy --only functions --project my-project-id

Confirmed by firebase.google.com

Did this fix it?

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 functions

Confirmed by github.com

Did this fix it?

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:

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.