mongodb/node-mongodb-native · error · MongoInvalidArgumentError

TOKEN_RESOURCE must be set in the auth mechanism properties…

Error message

TOKEN_RESOURCE must be set in the auth mechanism properties when ENVIRONMENT is azure or gcp.

What it means

Thrown by MongoCredentials.validate() when ENVIRONMENT is set to 'azure' or 'gcp' for MONGODB-OIDC but no TOKEN_RESOURCE (token audience) is supplied. The Azure and GCP metadata endpoints require an audience parameter to mint a token scoped to your MongoDB provider, so the driver refuses to proceed without it.

Solutions

Add TOKEN_RESOURCE to authMechanismProperties, set to the audience/URI your MongoDB provider expects (e.g. the Atlas/ImmuDB/Data Federation ARN or app ID).
For Azure: authMechanismProperties={ ENVIRONMENT:'azure', TOKEN_RESOURCE:'<audience>' }.
Verify the TOKEN_RESOURCE value matches what the identity provider is configured to issue tokens for.

Example fix

// before
new MongoClient(url, { auth: { mechanism:'MONGODB-OIDC', mechanismProperties:{ ENVIRONMENT:'azure' } } });
// after
new MongoClient(url, { auth: { mechanism:'MONGODB-OIDC', mechanismProperties:{ ENVIRONMENT:'azure', TOKEN_RESOURCE:'https://your-audience' } } });

Defensive patterns

Strategy: validation

Validate before calling

function assertOidcTokenResource(props) {
  if ((props?.ENVIRONMENT === 'azure' || props?.ENVIRONMENT === 'gcp') && !props?.TOKEN_RESOURCE) {
    throw new Error('TOKEN_RESOURCE is required for ENVIRONMENT azure/gcp.');
  }
}

Prevention

Always pair ENVIRONMENT:'azure'/'gcp' with a TOKEN_RESOURCE constant from config.
Add a startup self-test that validates mechanismProperties before connecting.
Document the required audience value next to the ENVIRONMENT setting.

When it happens

Trigger: Setting authMechanismProperties={ ENVIRONMENT: 'azure' } (or 'gcp') without a TOKEN_RESOURCE property. Occurs at connection/auth time inside validate().

Common situations: Following a tutorial that enables ENVIRONMENT=azure but omits the TOKEN_RESOURCE parameter. Assuming the cloud metadata endpoint returns a usable token without specifying the intended audience.

Related errors

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

Appendix: source

Thrown at src/cmap/auth/mongo_credentials.ts:213

        this.mechanismProperties.ENVIRONMENT !== 'azure'
      ) {
        throw new MongoInvalidArgumentError(
          `username and ENVIRONMENT '${this.mechanismProperties.ENVIRONMENT}' may not be used together for mechanism '${this.mechanism}'.`
        );
      }

      if (this.username && this.password) {
        throw new MongoInvalidArgumentError(
          `No password is allowed in ENVIRONMENT '${this.mechanismProperties.ENVIRONMENT}' for '${this.mechanism}'.`
        );
      }

      if (
        (this.mechanismProperties.ENVIRONMENT === 'azure' ||
          this.mechanismProperties.ENVIRONMENT === 'gcp') &&
        !this.mechanismProperties.TOKEN_RESOURCE
      ) {
        throw new MongoInvalidArgumentError(TOKEN_RESOURCE_MISSING_ERROR);
      }

      if (
        this.mechanismProperties.ENVIRONMENT &&
        !ALLOWED_ENVIRONMENT_NAMES.includes(this.mechanismProperties.ENVIRONMENT)
      ) {
        throw new MongoInvalidArgumentError(
          `Currently only a ENVIRONMENT in ${ALLOWED_ENVIRONMENT_NAMES.join(
            ','
          )} is supported for mechanism '${this.mechanism}'.`
        );
      }

      if (
        !this.mechanismProperties.ENVIRONMENT &&
        !this.mechanismProperties.OIDC_CALLBACK &&
        !this.mechanismProperties.OIDC_HUMAN_CALLBACK
      ) {

View on GitHub (pinned to dce7939f86)