{"record":{"id":"8cc7749a05f2a330","repo":"mongodb/node-mongodb-native","slug":"credentials-required-for-gssapi-authentication","errorCode":null,"errorMessage":"Credentials required for GSSAPI authentication","messagePattern":"Credentials required for GSSAPI authentication","errorType":"exception","errorClass":"MongoMissingCredentialsError","httpStatus":null,"severity":"error","filePath":"src/cmap/auth/gssapi.ts","lineNumber":43,"sourceCode":"  SERVICE_NAME?: string;\n  SERVICE_REALM?: string;\n};\n\nasync function externalCommand(\n  connection: Connection,\n  command: ReturnType<typeof saslStart> | ReturnType<typeof saslContinue>\n): Promise<{ payload: string; conversationId: number }> {\n  const response = await connection.command(ns('$external.$cmd'), command);\n  return response as { payload: string; conversationId: number };\n}\n\nlet krb: Kerberos;\n\nexport class GSSAPI extends AuthProvider {\n  override async auth(authContext: AuthContext): Promise<void> {\n    const { connection, credentials } = authContext;\n    if (credentials == null) {\n      throw new MongoMissingCredentialsError('Credentials required for GSSAPI authentication');\n    }\n\n    const { username } = credentials;\n\n    const client = await makeKerberosClient(authContext);\n\n    const payload = await client.step('');\n\n    const saslStartResponse = await externalCommand(connection, saslStart(payload));\n\n    const negotiatedPayload = await negotiate(client, 10, saslStartResponse.payload);\n\n    const saslContinueResponse = await externalCommand(\n      connection,\n      saslContinue(negotiatedPayload, saslStartResponse.conversationId)\n    );\n\n    const finalizePayload = await finalize(client, username, saslContinueResponse.payload);","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/auth/gssapi.ts#L25-L61","documentation":"Thrown at the start of GSSAPI (Kerberos) authentication when authContext.credentials is null/undefined. GSSAPI (MONGODB-GSSAPI) requires a username (principal) to build the Kerberos client; without credentials there is no principal to authenticate. It is a MongoMissingCredentialsError.","triggerScenarios":"Connecting with authMechanism=MONGODB-GSSAPI but no username in the URI or credentials; credentials stripped because the mechanism list didn't include GSSAPI; SERVICE_NAME/ SERVICE_HOST options set without a principal.","commonSituations":"URI like mongodb://host/?authMechanism=GSSAPI with no username@; the kerberos package present but the connection string missing the principal; authenticating to $external but providing a database other than $external.","solutions":["Include the Kerberos principal as the username: mongodb://user@REALM@host/?authMechanism=GSSAPI (note %40 escaping for the second @).","Ensure authSource is $external for GSSAPI (mongodb sets it, but explicit authSource=$external avoids ambiguity).","Confirm the `kerberos` npm package is installed (otherwise a different module error appears) and that a TGT is obtainable (kinit)."],"exampleFix":"// before\nconst c = new MongoClient('mongodb://host/?authMechanism=GSSAPI');\n// after\nconst c = new MongoClient(\n  'mongodb://appsvc%2Fhost.example.com%40EXAMPLE.COM@host/?authMechanism=GSSAPI&authSource=%24external'\n);","handlingStrategy":"validation","validationCode":"function assertGssapiPrincipal(uri) {\n  const u = new URL(uri);\n  if (/GSSAPI/i.test(uri) && !u.username) {\n    throw new Error('MONGODB-GSSAPI requires a username (Kerberos principal) in the URI');\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always include the Kerberos principal as username in a GSSAPI URI.","Set authSource=$external for GSSAPI.","Ensure `kinit` has obtained a TGT before connecting."],"tags":["auth","kerberos","gssapi","authentication","configuration"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}