{"record":{"id":"f46d8eb1cc864033","repo":"mongodb/node-mongodb-native","slug":"authcontext-must-provide-credentials-f46d8e","errorCode":null,"errorMessage":"AuthContext must provide credentials.","messagePattern":"AuthContext must provide credentials\\.","errorType":"exception","errorClass":"MongoMissingCredentialsError","httpStatus":null,"severity":"critical","filePath":"src/cmap/auth/plain.ts","lineNumber":10,"sourceCode":"import { Binary, ByteUtils } from '../../bson';\nimport { MongoMissingCredentialsError } from '../../error';\nimport { ns } from '../../utils';\nimport { type AuthContext, AuthProvider } from './auth_provider';\n\nexport class Plain extends AuthProvider {\n  override async auth(authContext: AuthContext): Promise<void> {\n    const { connection, credentials } = authContext;\n    if (!credentials) {\n      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');\n    }\n\n    const { username, password } = credentials;\n\n    const payload = new Binary(ByteUtils.fromUTF8(`\\x00${username}\\x00${password}`));\n    const command = {\n      saslStart: 1,\n      mechanism: 'PLAIN',\n      payload: payload,\n      autoAuthorize: 1\n    };\n\n    await connection.command(ns('$external.$cmd'), command, undefined);\n  }\n}\n","sourceCodeStart":1,"sourceCodeEnd":26,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/auth/plain.ts#L1-L26","documentation":"Thrown by the PLAIN (LDAP) auth provider (plain.ts:10) when the AuthContext has no credentials. PLAIN auth requires a username and password to build the SASL PLAIN payload (\\x00username\\x00password); without credentials the provider cannot construct it. Raised as MongoMissingCredentialsError.","triggerScenarios":"Connecting with authMechanism=PLAIN (LDAP) but no username/password in the connection string or options, or the credentials object failed to materialize during handshake.","commonSituations":"Using mongodb://host:port/?authMechanism=PLAIN with no user:pass in the URI. LDAP/AD setup where credentials are expected from a separate env source but never wired into MongoClient. authSource misconfiguration causing credentials to drop.","solutions":["Include username and password in the URI: mongodb://user:pass@host/?authMechanism=PLAIN&authSource=$external","Pass credentials programmatically via MongoClient options if not in the URI","Confirm authSource=$external for LDAP/PLAIN deployments"],"exampleFix":"// before\nconst uri = 'mongodb://ldap-host/?authMechanism=PLAIN';\n\n// after\nconst uri = 'mongodb://user:password@ldap-host/?authMechanism=PLAIN&authSource=$external';","handlingStrategy":"validation","validationCode":"if (clientOptions.auth?.mechanism === 'PLAIN') {\n  const u = clientOptions.auth?.username;\n  const p = clientOptions.auth?.password;\n  if (typeof u !== 'string' || typeof p !== 'string' || u === '' || p === '') {\n    throw new Error('PLAIN (LDAP) auth requires a username and password');\n  }\n}","typeGuard":"function hasPlainCreds(auth: { username?: unknown; password?: unknown }): auth is { username: string; password: string } {\n  return typeof auth.username === 'string' && typeof auth.password === 'string';\n}","tryCatchPattern":"try {\n  await client.connect();\n} catch (err) {\n  if (err instanceof MongoMissingCredentialsError && /PLAIN|LDAP/.test(err.message)) {\n    // prompt for LDAP creds and reconnect\n  } else throw err;\n}","preventionTips":["Always include user:pass in the URI for PLAIN/LDAP connections","Set authSource=$external explicitly for LDAP","Percent-encode special characters in the password"],"tags":["plain","ldap","authentication","credentials","configuration"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}