{"record":{"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":"exception","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/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/auth/mongo_credentials.ts#L170-L206","documentation":"Thrown by MongoCredentials.validate for the SCRAM (SHA-1/SHA-256), GSSAPI, and PLAIN mechanisms when no username is set. These mechanisms all authenticate a named principal; an empty username makes authentication impossible. It is a MongoMissingCredentialsError raised when credentials are first validated.","triggerScenarios":"Connecting with authMechanism=SCRAM-SHA-256 (default when a username is expected) or explicitly GSSAPI/PLAIN/SCRAM-SHA-1, but the URI/connection options have no username; credentials object built without username; username set to empty string.","commonSituations":"URI mongodb://host/db?authSource=admin with no user@ prefix; providing only a password; copying a connection string and dropping the user portion; MONGODB-X509 intended but authMechanism left as default SCRAM.","solutions":["Provide a username in the connection string: mongodb://user:password@host/db?authSource=admin.","If using X.509 (no username needed), set authMechanism=MONGODB-X509 explicitly.","If building credentials in code, pass { username, password } to the auth options."],"exampleFix":"// before\nnew MongoClient('mongodb://host/db?authSource=admin');\n// after\nnew MongoClient('mongodb://user:pass@host/db?authSource=admin');","handlingStrategy":"validation","validationCode":"function assertUsernameForMechanism(uri, mechanism) {\n  const scramLike = /^(SCRAM-SHA-1|SCRAM-SHA-256|GSSAPI|PLAIN)$/i.test(mechanism);\n  const u = new URL(uri);\n  if (scramLike && !u.username) {\n    throw new Error(`Username required for mechanism ${mechanism}`);\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Include user:pass@ in the URI for SCRAM/GSSAPI/PLAIN.","If you don't have a username, use MONGODB-X509 explicitly."],"tags":["auth","scram","authentication","configuration","credentials"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}