mongodb/node-mongodb-native · error · MongoInvalidArgumentError

username and ENVIRONMENT '${this.mechanismProperties.ENVIRON

Error message

username and ENVIRONMENT '${this.mechanismProperties.ENVIRONMENT}' may not be used together for mechanism '${this.mechanism}'.

What it means

Thrown for MONGODB-OIDC when both a username and an ENVIRONMENT (other than 'azure') are configured. For azure ENVIRONMENT a username (client_id) is allowed, but for gcp/k8s/test environments the machine identity is implied and a username must not be supplied. Mixing them is a configuration error.

Source

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

  validate(): void {
    if (
      (this.mechanism === AuthMechanism.MONGODB_GSSAPI ||
        this.mechanism === AuthMechanism.MONGODB_PLAIN ||
        this.mechanism === AuthMechanism.MONGODB_SCRAM_SHA1 ||
        this.mechanism === AuthMechanism.MONGODB_SCRAM_SHA256) &&
      !this.username
    ) {
      throw new MongoMissingCredentialsError(`Username required for mechanism '${this.mechanism}'`);
    }

    if (this.mechanism === AuthMechanism.MONGODB_OIDC) {
      if (
        this.username &&
        this.mechanismProperties.ENVIRONMENT &&
        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);
      }

View on GitHub (pinned to 3366c21a63)

Solutions

For gcp/k8s/test environments, remove the username from the connection string/options.
If you need a user principal, use ENVIRONMENT:azure (with client_id as username) or supply OIDC_CALLBACK/OIDC_HUMAN_CALLBACK without ENVIRONMENT.
Re-check the authMechanismProperties string format in the URI.

Example fix

// before
// 'mongodb://user@host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:...'

// after (no username for gcp machine identity)
// 'mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:...'

Defensive patterns

Strategy: validation

Validate before calling

function validateOidc(opts: { username?: string; mechanismProperties?: { ENVIRONMENT?: string } }) {
  const env = opts.mechanismProperties?.ENVIRONMENT;
  if (opts.username && env && env !== 'azure') {
    throw new Error(`username and ENVIRONMENT '${env}' may not be combined`);
  }
}

Type guard

import { MongoInvalidArgumentError } from 'mongodb';
function isOidcUserEnvConflict(e: unknown): boolean {
  return e instanceof MongoInvalidArgumentError && /username and ENVIRONMENT/.test(e.message);
}

Prevention

For gcp/k8s/test machine workflows, omit the username.
Reserve the username for ENVIRONMENT=azure (client_id) or callback-based flows.

When it happens

Trigger: In MongoCredentials.validate() OIDC branch when username is set, ENVIRONMENT is set, and ENVIRONMENT !== 'azure'.

Common situations: Configuring OIDC with authMechanism=MONGODB-OIDC plus authMechanismProperties=ENVIRONMENT:gcp while also passing a username intended for a callback; misunderstanding that gcp/k8s machine workflows take no user principal.

Related errors

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