Maaz Zindani

Loading the index…

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

process.env.MY_VARIABLE is undefined even though it is in the .env file

Errorconsole.log(process.env.PORT) prints undefined

Short answer

process.env only holds variables that exist in the process environment. Node.js does not load a .env file unless you ask it to, with the --env-file flag or a library such as dotenv. Load the file before any code reads the variable, and start the app from the folder that holds it.

  • Applies to Node.js 22, Node.js 24, dotenv 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print every variable name the process can see. If your key is not in the list, the file was never loaded.

    node -e "console.log(Object.keys(process.env).filter(k => k.includes('PORT')))"
  2. 2Match what you see, then jump to its fix

    1. 1The key is missing from the list above, and no flag or library loads the fileNothing loads the .env fileFix
    2. 2dotenv is installed, yet a module-level constant is still undefineddotenv runs after the code that reads the variableFix
    3. 3Works with npm start in the project root, fails from a process manager, systemd or a script in another folderThe app starts from a different folder than the one with .envFix
    4. 4The value is not undefined but it is not the one in the fileThe variable already exists in the shell with another valueFix

What does the error look like?

  • console.log(process.env.PORT) prints undefined

Cause 1 of 4

Nothing loads the .env file

1Check

Look at how the app starts. A plain node index.js reads no file.

grep -n "dotenv\|env-file" package.json
grep -rn "dotenv" --include=*.js --include=*.mjs --include=*.ts . --exclude-dir=node_modules | head

2Fix

Start Node.js with --env-file (added in v20.6.0), or use dotenv. If the file may be absent in production, use --env-file-if-exists (v22.9.0 and later).

node --env-file=.env index.js

3Verify

The value now prints.

node --env-file=.env -e "console.log(process.env.PORT)"

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 4

dotenv runs after the code that reads the variable

1Check

Imports run first. If another module reads process.env while it is being imported, dotenv has not run yet. In ES modules, imports are evaluated in order, so the dotenv import must come first.

grep -n "import\|require" index.js | head

2Fix

Load dotenv as the very first line of the entry file.

// index.mjs
import 'dotenv/config';
import './server.mjs';

3Verify

The first read after startup returns the value.

node index.mjs

Confirmed by github.com

Did this fix it?

Cause 3 of 4

The app starts from a different folder than the one with .env

1Check

Both --env-file and dotenv look for the path relative to the current working directory. A missing file given to --env-file raises an error, but a dotenv default load simply finds nothing.

pwd
ls -la .env

2Fix

Run from the project folder, or pass an absolute path.

node --env-file=/srv/my-app/.env /srv/my-app/index.js

3Verify

Run it from any folder.

cd / && node --env-file=/srv/my-app/.env -e "console.log(process.env.PORT)"

Confirmed by nodejs.org

Did this fix it?

Cause 4 of 4

The variable already exists in the shell with another value

1Check

When a variable is set in both the environment and the file, the environment value wins. dotenv also skips keys that already exist unless override is true.

printenv PORT

2Fix

Unset the shell variable, or in dotenv enable override.

unset PORT
# or, in code:
require('dotenv').config({ override: true });

3Verify

The value now comes from the file.

node --env-file=.env -e "console.log(process.env.PORT)"

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Load the env file in one place: the start script or the first import of the entry file.
  • Give production values through the process manager or host, and keep .env for local work.
  • Fail fast at startup when a required variable is missing instead of letting undefined travel.

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

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

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.