mongodb/node-mongodb-native · error · MongoInvalidArgumentError

username and ENVIRONMENT

Error message

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

What it means

Thrown by MongoCredentials.validate for MONGODB-OIDC when both a username and a non-azure ENVIRONMENT are configured. For the azure OIDC environment the username doubles as the client_id and is allowed, but for other managed environments (gcp, k8s, etc.) the identity is provided by the environment itself, so an explicit username is contradictory. It is a MongoInvalidArgumentError.

Solutions

1. For non-azure OIDC environments, remove the username from the connection string / credentials.
2. If you need OIDC with a username principal, use ENVIRONMENT=azure (where username = client_id) or no ENVIRONMENT (callback/IdP flow with a username).
3. Double-check mechanismProperties: { ENVIRONMENT: 'gcp' } should be paired with no username.

Example fix

// before
new MongoClient('mongodb://user@host/?authMechanism=MONGODB-OIDC', {
  authMechanismProperties: { ENVIRONMENT: 'gcp', TOKEN_RESOURCE: '...' }
});
// after: drop the username for non-azure environments
new MongoClient('mongodb://host/?authMechanism=MONGODB-OIDC', {
  authMechanismProperties: { ENVIRONMENT: 'gcp', TOKEN_RESOURCE: '...' }
});

function assertOidcEnvUsernameConsistent(uri, mechanismProperties) {
  const u = new URL(uri);
  const env = mechanismProperties?.ENVIRONMENT;
  if (u.username && env && env !== 'azure') {
    throw new Error(`username is not allowed with OIDC ENVIRONMENT='${env}' (only 'azure')`);
  }
}

When it happens

Trigger: Configuring OIDC with authMechanism=MONGODB-OIDC, mechanismProperties.ENVIRONMENT set to something other than 'azure', and also supplying a username in the connection string/credentials.

Common situations: Copying an Azure OIDC URI (which legitimately includes username=client_id) and changing ENVIRONMENT to gcp/awsvpc/k8s without removing the username; building credentials generically and always setting username.

Related errors

• Auth mechanism property ALLOWED_HOSTS must be an array of…
• AuthContext must provide credentials.
• Credentials required for GSSAPI authentication
• Currently only a ENVIRONMENT in
• Either a ENVIRONMENT, OIDC_CALLBACK, or OIDC_HUMAN_CALLBACK…

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

Appendix: 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 dce7939f86)