{"id":"5a9d549bd9dae601","repo":"mongodb/node-mongodb-native","slug":"username-and-environment-this-mechanismproperti","errorCode":null,"errorMessage":"username and ENVIRONMENT '${this.mechanismProperties.ENVIRONMENT}' may not be used together for mechanism '${this.mechanism}'.","messagePattern":"username and ENVIRONMENT '(.+?)' may not be used together for mechanism '(.+?)'\\.","errorType":"validation","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/cmap/auth/mongo_credentials.ts","lineNumber":197,"sourceCode":"\n  validate(): void {\n    if (\n      (this.mechanism === AuthMechanism.MONGODB_GSSAPI ||\n        this.mechanism === AuthMechanism.MONGODB_PLAIN ||\n        this.mechanism === AuthMechanism.MONGODB_SCRAM_SHA1 ||\n        this.mechanism === AuthMechanism.MONGODB_SCRAM_SHA256) &&\n      !this.username\n    ) {\n      throw new MongoMissingCredentialsError(`Username required for mechanism '${this.mechanism}'`);\n    }\n\n    if (this.mechanism === AuthMechanism.MONGODB_OIDC) {\n      if (\n        this.username &&\n        this.mechanismProperties.ENVIRONMENT &&\n        this.mechanismProperties.ENVIRONMENT !== 'azure'\n      ) {\n        throw new MongoInvalidArgumentError(\n          `username and ENVIRONMENT '${this.mechanismProperties.ENVIRONMENT}' may not be used together for mechanism '${this.mechanism}'.`\n        );\n      }\n\n      if (this.username && this.password) {\n        throw new MongoInvalidArgumentError(\n          `No password is allowed in ENVIRONMENT '${this.mechanismProperties.ENVIRONMENT}' for '${this.mechanism}'.`\n        );\n      }\n\n      if (\n        (this.mechanismProperties.ENVIRONMENT === 'azure' ||\n          this.mechanismProperties.ENVIRONMENT === 'gcp') &&\n        !this.mechanismProperties.TOKEN_RESOURCE\n      ) {\n        throw new MongoInvalidArgumentError(TOKEN_RESOURCE_MISSING_ERROR);\n      }\n","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cmap/auth/mongo_credentials.ts#L179-L215","documentation":"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.","triggerScenarios":"In MongoCredentials.validate() OIDC branch when username is set, ENVIRONMENT is set, and ENVIRONMENT !== 'azure'.","commonSituations":"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.","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."],"exampleFix":"// before\n// 'mongodb://user@host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:...'\n\n// after (no username for gcp machine identity)\n// 'mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:...'","handlingStrategy":"validation","validationCode":"function validateOidc(opts: { username?: string; mechanismProperties?: { ENVIRONMENT?: string } }) {\n  const env = opts.mechanismProperties?.ENVIRONMENT;\n  if (opts.username && env && env !== 'azure') {\n    throw new Error(`username and ENVIRONMENT '${env}' may not be combined`);\n  }\n}","typeGuard":"import { MongoInvalidArgumentError } from 'mongodb';\nfunction isOidcUserEnvConflict(e: unknown): boolean {\n  return e instanceof MongoInvalidArgumentError && /username and ENVIRONMENT/.test(e.message);\n}","tryCatchPattern":null,"preventionTips":["For gcp/k8s/test machine workflows, omit the username.","Reserve the username for ENVIRONMENT=azure (client_id) or callback-based flows."],"tags":["auth","oidc","credentials","configuration"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}