A .env file on disk is not automatically the environment of every Node process. On Node versions with native --env-file support, load the intended file at startup and check the variable after loading, without printing secret values.
Reproduce the boundary in a disposable fixture
Separate environment-file loading, startup path and already-set variable precedence.
Use a new empty temporary directory for this fixture. The example creates only local test data. Commands marked with example.invalid do not identify a real service.
const assert = require('node:assert/strict');
const fs = require('node:fs');
const {spawnSync} = require('node:child_process');
fs.writeFileSync('fixture.env', 'FIXTURE_ENV_VALUE=from_file\n');
const env = {...process.env};
delete env.FIXTURE_ENV_VALUE;
function run(args, customEnv) {
const r = spawnSync(process.execPath, args, {env:customEnv, encoding:'utf8'});
assert.equal(r.status,0,r.stderr);
return r.stdout.trim();
}
const probe = "console.log(process.env.FIXTURE_ENV_VALUE ?? 'absent')";
assert.equal(run(['-e',probe], env),'absent');
assert.equal(run(['--env-file=fixture.env','-e',probe],env),'from_file');
assert.equal(run(['--env-file=fixture.env','-e',probe],
{...env,FIXTURE_ENV_VALUE:'from_parent'}),'from_parent');
console.log('loading and precedence verified');Observed result
loading and precedence verifiedWhat the result means
The first child never loads the file. The second loads it explicitly. The third demonstrates that an already-present environment variable wins over the value in that file. This isolates three causes that can all look like a configuration edit having no effect: no loader, wrong startup location, or a value supplied by the parent process.
Choose the correction for your workflow
Confirm the actual Node executable and its --help before selecting native flags; --env-file was introduced in Node 20.6.0 and is unavailable on older releases. Use the exact startup command in development and deployment, with a file path resolved from that process working directory. If a project already uses a library loader, read its ordering and precedence instead of combining loaders casually. Ensure loading happens before modules capture environment values during initialization. To diagnose safely, report whether a required variable is present and valid rather than dumping process.env.
Limits and the next check
This is a native Node startup fixture on the recorded installed version, not a test of a framework, browser bundle, CI secret or hosting platform. Browser JavaScript does not inherit a Node process environment. A correct file cannot fix a misspelled key, an intentionally empty value or a module that already captured stale state. Preserve the project existing secret-handling policy and do not commit private .env files for convenience.
Related: Compare the related workflow boundary.
This isolated example was executed on macOS on November 10, 2026 (KST). Available tools: node v26.5.0, git git version 2.39.3 (Apple Git-145), npm 11.17.0, jq jq-1.7.1-apple. Shell fixtures use Bash and repository-path identity uses Python 3. This checks the illustrated contract, not your project, host service or every tool version.