mongodb/node-mongodb-native · error · MongoMissingCredentialsError

Credentials required for GSSAPI authentication

Error message

Credentials required for GSSAPI authentication

What it means

Thrown by the GSSAPI (Kerberos) auth provider when authContext.credentials is null/undefined at the start of authentication. The driver cannot construct a Kerberos client principal without a username (and optional password). GSSAPI requires at least a username to form the client ticket request.

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 3366c21a63)

Solutions

1. Provide the Kerberos principal as the username in the connection string: 'mongodb://user@REALM@host/?authMechanism=GSSAPI'.
2. Pass username in the credentials option of MongoClient.
3. URL-encode any special characters in the principal (the '@' separating realm).

Example fix

// before
const c = new MongoClient('mongodb://host/?authMechanism=GSSAPI');

// after
const c = new MongoClient('mongodb://appsvc%40REALM@host/?authMechanism=GSSAPI');

function requirePrincipal(uri: string): void {
  if (/authMechanism=GSSAPI/i.test(uri) && !/\/\/[^/?]*%40|@/.test(uri)) {
    throw new Error('GSSAPI requires a username (principal) in the URI');
  }
}

import { MongoMissingCredentialsError } from 'mongodb';
function isGSSAPICredentialsError(e: unknown): boolean {
  return e instanceof MongoMissingCredentialsError && /GSSAPI/.test(e.message);
}

When it happens

Trigger: In GSSAPI.auth() when credentials is null; happens when authMechanism='GSSAPI' is set but no username was resolved from the connection string or credentials object.

Common situations: Connection string like 'mongodb://host/?authMechanism=GSSAPI' with no username; credentials object passed to MongoClient missing username; URI-encoded username stripped by mis-parsing; using GSSAPI without supplying a Kerberos principal.

Related errors

• Username required for mechanism '${this.mechanism}'
• Invalid source '${this.source}' for mechanism '${this.mechan
• Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}
• username and ENVIRONMENT '${this.mechanismProperties.ENVIRON
• No password is allowed in ENVIRONMENT '${this.mechanismPrope

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/8cc7749a05f2a330.json. Report an issue: GitHub.