mongodb/node-mongodb-native · error · MongoMissingCredentialsError

Credentials required for GSSAPI authentication

Error message

Credentials required for GSSAPI authentication

What it means

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.

Solutions

1. Include the Kerberos principal as the username: mongodb://user@REALM@host/?authMechanism=GSSAPI (note %40 escaping for the second @).
2. Ensure authSource is $external for GSSAPI (mongodb sets it, but explicit authSource=$external avoids ambiguity).
3. Confirm the `kerberos` npm package is installed (otherwise a different module error appears) and that a TGT is obtainable (kinit).

Example fix

// before
const c = new MongoClient('mongodb://host/?authMechanism=GSSAPI');
// after
const c = new MongoClient(
  'mongodb://appsvc%2Fhost.example.com%40EXAMPLE.COM@host/?authMechanism=GSSAPI&authSource=%24external'
);

function assertGssapiPrincipal(uri) {
  const u = new URL(uri);
  if (/GSSAPI/i.test(uri) && !u.username) {
    throw new Error('MONGODB-GSSAPI requires a username (Kerberos principal) in the URI');
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Invalid CANONICALIZE_HOST_NAME value
• Connection must have host and port and credentials defined.
• username and ENVIRONMENT
• Username required for mechanism
• Auth mechanism property ALLOWED_HOSTS must be an array of…

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/8cc7749a05f2a330. Report an issue: GitHub.

Appendix: source

Thrown at src/cmap/auth/gssapi.ts:43

  SERVICE_NAME?: string;
  SERVICE_REALM?: string;
};

async function externalCommand(
  connection: Connection,
  command: ReturnType<typeof saslStart> | ReturnType<typeof saslContinue>
): Promise<{ payload: string; conversationId: number }> {
  const response = await connection.command(ns('$external.$cmd'), command);
  return response as { payload: string; conversationId: number };
}

let krb: Kerberos;

export class GSSAPI extends AuthProvider {
  override async auth(authContext: AuthContext): Promise<void> {
    const { connection, credentials } = authContext;
    if (credentials == null) {
      throw new MongoMissingCredentialsError('Credentials required for GSSAPI authentication');
    }

    const { username } = credentials;

    const client = await makeKerberosClient(authContext);

    const payload = await client.step('');

    const saslStartResponse = await externalCommand(connection, saslStart(payload));

    const negotiatedPayload = await negotiate(client, 10, saslStartResponse.payload);

    const saslContinueResponse = await externalCommand(
      connection,
      saslContinue(negotiatedPayload, saslStartResponse.conversationId)
    );

    const finalizePayload = await finalize(client, username, saslContinueResponse.payload);

View on GitHub (pinned to dce7939f86)