{"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":"critical","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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cmap/auth/x509.ts#L1-L33","documentation":"Thrown by X509.prepare() (x509.ts:15) as a MongoMissingCredentialsError when the AuthContext has no credentials during the X.509 speculative authentication setup. X.509 auth presents a client certificate; without a credentials object the driver cannot build the authenticate command. Most often a connection-string/configuration problem.","triggerScenarios":"Connecting with authMechanism=MONGODB-X509 but no username and no TLS client certificate configured; X509 selected via auto-negotiation without a credentials source; programmatic AuthContext construction without credentials.","commonSituations":"Forgetting to set tlsCertificateKeyFile when using X.509; mixing up MONGODB-X509 with MONGODB-AWS; connecting to a $external user store without configuring client certificates.","solutions":["Provide a username (the certificate subject) in the connection string or auth option","Configure TLS client certificates: tlsCertificateKeyFile and tlsCAFile options","Ensure the authSource is $external for X.509","Verify the server has the client certificate's CA configured"],"exampleFix":"// before\nconst client = new MongoClient('mongodb://host/?authMechanism=MONGODB-X509');\n// after\nconst client = new MongoClient('mongodb://CN=user@host/?authMechanism=MONGODB-X509&authSource=$external&tlsCertificateKeyFile=./client.pem&tlsCAFile=./ca.pem');","handlingStrategy":"validation","validationCode":"function hasX509Credentials(opts: { username?: string; tlsCertificateKeyFile?: string }): boolean {\n  return Boolean(opts.username && opts.tlsCertificateKeyFile);\n}\nif (!hasX509Credentials(clientOptions)) throw new Error('X509 auth requires a username and tlsCertificateKeyFile');","typeGuard":"interface X509Opts { username: string; tlsCertificateKeyFile: string; tlsCAFile: string; authSource: '$external'; }\nfunction isX509Configured(o: any): o is X509Opts {\n  return typeof o.username === 'string' && typeof o.tlsCertificateKeyFile === 'string';\n}","tryCatchPattern":"try {\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoMissingCredentialsError && /MONGODB-X509|credentials/i.test(e.message)) {\n    // provide username + tlsCertificateKeyFile in client options\n  }\n  throw e;\n}","preventionTips":["Always set authSource=$external with MONGODB-X509","Provide the certificate subject as the username","Configure tlsCertificateKeyFile and tlsCAFile for X.509"],"tags":["auth","x509","credentials","tls"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}