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

Set the OIDC_TOKEN_FILE environment variable to the absolute path of the file containing the OIDC access token.

mongodb/node-mongodb-native · error · 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 token machine OIDC workflow when the OIDC_TOKEN_FILE environment variable is not set (src/cmap/auth/mongodb_oidc/token_machine_workflow.ts:17). This workflow (registered as the 'test' environment) reads the access token from a file path pointed to by OIDC_TOKEN_FILE. Surfaced as a MongoAWSError.

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 3366c21a63)

Solutions

Set the OIDC_TOKEN_FILE environment variable to the absolute path of the file containing the OIDC access token.
Ensure the variable is exported in the same process/shell that runs the Node application.
If running in containers, pass the env var and mount the token file into the container.
If you did not intend the test environment, remove ENVIRONMENT:test and use azure/gcp/k8s or a callback workflow instead.

Example fix

# before
export OIDC_ENV=test
node app.js   # OIDC_TOKEN_FILE unset -> error

# after
export OIDC_TOKEN_FILE=/var/run/secrets/tokens/mongodb-oidc-token
node app.js

Defensive patterns

Strategy: validation

Validate before calling

function assertOidcTokenFileEnv(): void {
  if (process.env.OIDC_TOKEN_FILE == null || process.env.OIDC_TOKEN_FILE === '') {
    throw new Error('OIDC_TOKEN_FILE must be set in the environment when using ENVIRONMENT=test');
  }
}
assertOidcTokenFileEnv();

Try / catch

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoAWSError && /OIDC_TOKEN_FILE/.test(e.message)) {
    throw new Error('Set OIDC_TOKEN_FILE to the path of the file containing the OIDC token.');
  }
  throw e;
}

Prevention

Set OIDC_TOKEN_FILE in the process environment (and container spec) before app start.
If using a token-refreshing sidecar, ensure the file path is stable and the env var points to it.
Document the required env var in deployment manifests for the 'test' environment.

When it happens

Trigger: Connecting with MONGODB-OIDC and authMechanismProperties=ENVIRONMENT:test without the OIDC_TOKEN_FILE environment variable defined. The workflow reads process.env.OIDC_TOKEN_FILE and throws before any file read.

Common situations: Using the 'test' OIDC environment (commonly for driver spec tests or spire/spire-style workload identity where a sidecar writes a token file) but forgetting to set OIDC_TOKEN_FILE in the process environment, or setting it in a different shell than the one running the driver.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/b8def113d53ce7d4.json. Report an issue: GitHub.