{"record":{"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":"exception","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/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/auth/mongo_credentials.ts#L179-L215","documentation":"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.","triggerScenarios":"Configuring OIDC with authMechanism=MONGODB-OIDC, mechanismProperties.ENVIRONMENT set to something other than 'azure', and also supplying a username in the connection string/credentials.","commonSituations":"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.","solutions":["For non-azure OIDC environments, remove the username from the connection string / credentials.","If you need OIDC with a username principal, use ENVIRONMENT=azure (where username = client_id) or no ENVIRONMENT (callback/IdP flow with a username).","Double-check mechanismProperties: { ENVIRONMENT: 'gcp' } should be paired with no username."],"exampleFix":"// before\nnew MongoClient('mongodb://user@host/?authMechanism=MONGODB-OIDC', {\n  authMechanismProperties: { ENVIRONMENT: 'gcp', TOKEN_RESOURCE: '...' }\n});\n// after: drop the username for non-azure environments\nnew MongoClient('mongodb://host/?authMechanism=MONGODB-OIDC', {\n  authMechanismProperties: { ENVIRONMENT: 'gcp', TOKEN_RESOURCE: '...' }\n});","handlingStrategy":"validation","validationCode":"function assertOidcEnvUsernameConsistent(uri, mechanismProperties) {\n  const u = new URL(uri);\n  const env = mechanismProperties?.ENVIRONMENT;\n  if (u.username && env && env !== 'azure') {\n    throw new Error(`username is not allowed with OIDC ENVIRONMENT='${env}' (only 'azure')`);\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["For non-azure OIDC environments, omit the username entirely.","Reserve username=client_id for the azure OIDC environment only.","Build OIDC option sets in one place so the ENVIRONMENT/username rule is enforced once."],"tags":["auth","oidc","authentication","configuration"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}