What causes "OIDC_TOKEN_FILE must be set in the environment." in mongodb/node-mongodb-native?

Export OIDC_TOKEN_FILE pointing to a readable file containing the OIDC access token: export OIDC_TOKEN_FILE=/var/run/secrets/token

mongodb/node-mongodb-native · critical · MongoAWSError

OIDC_TOKEN_FILE must be set in the environment.

Error message

OIDC_TOKEN_FILE must be set in the environment.

What it means

Thrown by the OIDC test machine workflow (token_machine_workflow.ts:18) when the OIDC_TOKEN_FILE environment variable is unset. This workflow reads a raw OIDC access token from the file at process.env.OIDC_TOKEN_FILE and is registered for ENVIRONMENT=test (mongodb_oidc.ts:124). It is intended for driver testing, not production authentication. Raised as MongoAWSError.

Solutions

Export OIDC_TOKEN_FILE pointing to a readable file containing the OIDC access token: export OIDC_TOKEN_FILE=/var/run/secrets/token
Ensure the file exists, is readable by the process, and contains a single valid token string
For production, use a supported cloud environment (gcp/azure/k8s) or supply your own callback instead of ENVIRONMENT=test

Example fix

# before
URI='mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:test'
node app.js   # OIDC_TOKEN_FILE not set -> MongoAWSError

# after
export OIDC_TOKEN_FILE=/var/run/secrets/mongodb-oidc/token
URI='mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:test'
node app.js

Defensive patterns

Strategy: validation

Validate before calling

if (process.env.OIDC_TOKEN_FILE === undefined || process.env.OIDC_TOKEN_FILE === '') {
  throw new Error('OIDC_TOKEN_FILE env var must be set for ENVIRONMENT=test OIDC auth');
}

Try / catch

try {
  await client.connect();
} catch (err) {
  if (err instanceof MongoAWSError && /OIDC_TOKEN_FILE/.test(err.message)) {
    process.env.OIDC_TOKEN_FILE = '/var/run/secrets/mongodb-oidc/token';
    await client.connect();
  } else throw err;
}

Prevention

Validate required env vars at process startup before constructing MongoClient
Keep ENVIRONMENT=test for tests only; use a real environment or callback in production
Document OIDC_TOKEN_FILE in your deployment runbook

When it happens

Trigger: Connecting with authMechanism='MONGODB-OIDC' and authMechanismProperties.ENVIRONMENT='test' (which selects tokenMachineCallback) while the OIDC_TOKEN_FILE environment variable is not exported, or is set to an empty string.

Common situations: Running OIDC test suites locally without exporting OIDC_TOKEN_FILE. A CI job that uses the test workflow but forgets to inject the env var. Accidentally using ENVIRONMENT=test in a non-test deployment expecting it to read another token source.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/b8def113d53ce7d4. Report an issue: GitHub.

Appendix: source

Thrown at src/cmap/auth/mongodb_oidc/token_machine_workflow.ts:18

import * as fs from 'fs';
import * as process from 'process';

import { MongoAWSError } from '../../../error';
import type { OIDCCallbackFunction, OIDCResponse } from '../mongodb_oidc';

/** Error for when the token is missing in the environment. */
const TOKEN_MISSING_ERROR = 'OIDC_TOKEN_FILE must be set in the environment.';

/**
 * The callback function to be used in the automated callback workflow.
 * @param params - The OIDC callback parameters.
 * @returns The OIDC response.
 */
export const tokenMachineCallback: OIDCCallbackFunction = async (): Promise<OIDCResponse> => {
  const tokenFile = process.env.OIDC_TOKEN_FILE;
  if (!tokenFile) {
    throw new MongoAWSError(TOKEN_MISSING_ERROR);
  }
  const token = await fs.promises.readFile(tokenFile, 'utf8');
  return { accessToken: token };
};

View on GitHub (pinned to dce7939f86)