{"id":"726bab1b10e01a17","repo":"mongodb/node-mongodb-native","slug":"username-required-for-mechanism-this-mechanism","errorCode":null,"errorMessage":"Username required for mechanism '${this.mechanism}'","messagePattern":"Username required for mechanism '(.+?)'","errorType":"validation","errorClass":"MongoMissingCredentialsError","httpStatus":null,"severity":"error","filePath":"src/cmap/auth/mongo_credentials.ts","lineNumber":188,"sourceCode":"        password: this.password,\n        source: this.source,\n        mechanism: getDefaultAuthMechanism(hello),\n        mechanismProperties: this.mechanismProperties\n      });\n    }\n\n    return this;\n  }\n\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      }","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cmap/auth/mongo_credentials.ts#L170-L206","documentation":"Thrown by MongoCredentials.validate() when the auth mechanism is one of GSSAPI, PLAIN, SCRAM-SHA-1, or SCRAM-SHA-256 but no username was provided. These mechanisms all require a username to perform authentication. X509 and AWS and OIDC have their own rules and are handled separately.","triggerScenarios":"In MongoCredentials.validate() during connection setup when mechanism is in the SCRAM/GSSAPI/PLAIN set and username is empty.","commonSituations":"Connection string missing the username component; credentials object created without username; SCRAM auth attempted with only a password; copy/paste connection string that dropped the user@ prefix.","solutions":["Add the username to the connection string: 'mongodb://username:password@host/?authSource=...'.","Pass { auth: { username, password } } in MongoClient options.","Confirm the username wasn't stripped by URL parsing (encode special chars)."],"exampleFix":"// before\nnew MongoClient('mongodb://host/?authSource=admin');\n\n// after\nnew MongoClient('mongodb://alice:secret@host/?authSource=admin');","handlingStrategy":"validation","validationCode":"function validateCredentials(opts: { username?: string; mechanism?: string }) {\n  const mechs = ['GSSAPI','PLAIN','SCRAM-SHA-1','SCRAM-SHA-256'];\n  if (opts.mechanism && mechs.includes(opts.mechanism) && !opts.username) {\n    throw new Error(`Username required for mechanism ${opts.mechanism}`);\n  }\n}","typeGuard":"import { MongoMissingCredentialsError } from 'mongodb';\nfunction isUsernameRequired(e: unknown): boolean {\n  return e instanceof MongoMissingCredentialsError && /Username required for mechanism/.test(e.message);\n}","tryCatchPattern":null,"preventionTips":["Always include a username in connection strings for SCRAM/GSSAPI/PLAIN.","Centralize connection-string building to avoid dropping the user@ segment."],"tags":["auth","credentials","scram","gssapi","plain"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}