{"record":{"id":"f04d4e2ac5e76872","repo":"mongodb/node-mongodb-native","slug":"authcontext-must-provide-credentials-f04d4e","errorCode":null,"errorMessage":"AuthContext must provide credentials.","messagePattern":"AuthContext must provide credentials\\.","errorType":"exception","errorClass":"MongoMissingCredentialsError","httpStatus":null,"severity":"error","filePath":"src/cmap/auth/x509.ts","lineNumber":15,"sourceCode":"import type { Document } from '../../bson';\nimport { MongoMissingCredentialsError } from '../../error';\nimport { ns } from '../../utils';\nimport type { HandshakeDocument } from '../connect';\nimport { type AuthContext, AuthProvider } from './auth_provider';\nimport type { MongoCredentials } from './mongo_credentials';\n\nexport class X509 extends AuthProvider {\n  override async prepare(\n    handshakeDoc: HandshakeDocument,\n    authContext: AuthContext\n  ): Promise<HandshakeDocument> {\n    const { credentials } = authContext;\n    if (!credentials) {\n      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');\n    }\n    return { ...handshakeDoc, speculativeAuthenticate: x509AuthenticateCommand(credentials) };\n  }\n\n  override async auth(authContext: AuthContext) {\n    const connection = authContext.connection;\n    const credentials = authContext.credentials;\n    if (!credentials) {\n      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');\n    }\n    const response = authContext.response;\n\n    if (response?.speculativeAuthenticate) {\n      return;\n    }\n\n    await connection.command(ns('$external.$cmd'), x509AuthenticateCommand(credentials), undefined);\n  }","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/auth/x509.ts#L1-L33","documentation":"Thrown as a MongoMissingCredentialsError in X509.prepare() when authContext.credentials is falsy. prepare() builds the speculativeAuthenticate portion of the handshake for MONGODB-X509; without credentials there is no subject to authenticate. This fires during the initial handshake document construction (prepareHandshakeDocument).","triggerScenarios":"Configuring the driver with authMechanism=MONGODB-X509 (or having it resolved to MONGODB-X509) but providing no credentials object, or a credentials object that resolves to null. The provider's prepare() is invoked from prepareHandshakeDocument() during connect().","commonSituations":"Setting ?authMechanism=MONGODB-X509 in the URI without a username; using x509 for inter-cluster auth but forgetting to pass the client certificate subject as the username; misconfigured service mesh that strips credentials.","solutions":["Provide credentials with the X.509 subject as username: new MongoClient(url, { auth: { username: 'CN=...,OU=...' }, authMechanism: 'MONGODB-X509' })","Ensure the TLS certificate (cert/key) is configured via tlsCertFile/tlsKeyFile so the server can identify the client","Verify the credentials object is not being stripped or overwritten before connect()"],"exampleFix":"// before\nconst client = new MongoClient('mongodb://host/db?authMechanism=MONGODB-X509&tls=true');\n\n// after\nconst client = new MongoClient('mongodb://host/db?tls=true', {\n  authMechanism: 'MONGODB-X509',\n  tlsCertFile: './client.pem',\n  auth: { username: 'CN=client,OU=eng,O=myorg' }\n});","handlingStrategy":"validation","validationCode":"if (options.authMechanism === 'MONGODB-X509' && !(options.auth?.username)) {\n  throw new Error('MONGODB-X509 requires the certificate subject as username');\n}","typeGuard":"function hasX509Credentials(opts: { authMechanism?: string; auth?: { username?: string } }): boolean {\n  return opts.authMechanism === 'MONGODB-X509' && typeof opts.auth?.username === 'string' && opts.auth.username.length > 0;\n}","tryCatchPattern":"try { await client.connect(); } catch (e) {\n  if (e instanceof MongoMissingCredentialsError) { /* supply X509 username */ }\n  throw e;\n}","preventionTips":["Always pass the X.509 certificate subject as the username for MONGODB-X509","Configure tlsCertFile/tlsKeyFile alongside the X509 mechanism","Centralize X509 subject extraction from the certificate so the username is always set"],"tags":["authentication","x509","tls","credentials"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}