mongodb/node-mongodb-native · critical · MongoMissingCredentialsError

AuthContext must provide credentials.

Error message

AuthContext must provide credentials.

What it means

Thrown by ScramSHA.prepare (scram.ts:32) when the AuthContext has no credentials during the speculative-authentication handshake step. SCRAM needs username/password/source to build the first SASL message, so a missing credentials object aborts prepare. Raised as MongoMissingCredentialsError.

Solutions

1. Provide username and password in the connection string
2. If authenticating to a specific db, set authSource appropriately
3. When building MongoClient programmatically, pass auth: { username, password }

Example fix

// before
const client = new MongoClient('mongodb://cluster.example.net');

// after
const client = new MongoClient('mongodb://user:pass@cluster.example.net/?authSource=admin');

const u = clientOptions.auth?.username;
const p = clientOptions.auth?.password;
if ((u === undefined || p === undefined) && !/:[^:@]+@/.test(uri)) {
  throw new Error('SCRAM auth requires username and password');
}

function hasScramCreds(auth: { username?: unknown; password?: unknown }): auth is { username: string; password: string } {
  return typeof auth.username === 'string' && typeof auth.password === 'string' && auth.password.length > 0;
}

try {
  await client.connect();
} catch (err) {
  if (err instanceof MongoMissingCredentialsError) {
    // gather credentials (e.g., secret manager) and reconnect
  } else throw err;
}

When it happens

Trigger: Connecting with SCRAM-SHA-1 or SCRAM-SHA-256 (the default) but the AuthContext.credentials is null, typically because no username/password were supplied and the server requires authentication.

Common situations: Connecting to an authenticated cluster with mongodb://host:port (no credentials). Default mechanism auto-selection picking SCRAM on a server that requires auth. A programmatic MongoClient with no auth options against an auth-enabled deployment.

Related errors

• Password cannot be empty
• Username required for mechanism
• AuthContext must provide credentials.
• AuthContext must provide credentials.
• AuthContext must provide credentials.

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

Appendix: source

Thrown at src/cmap/auth/scram.ts:32

type CryptoMethod = 'sha1' | 'sha256';

class ScramSHA extends AuthProvider {
  cryptoMethod: CryptoMethod;

  constructor(cryptoMethod: CryptoMethod) {
    super();
    this.cryptoMethod = cryptoMethod || 'sha1';
  }

  override async prepare(
    handshakeDoc: HandshakeDocument,
    authContext: AuthContext
  ): Promise<HandshakeDocument> {
    const cryptoMethod = this.cryptoMethod;
    const credentials = authContext.credentials;
    if (!credentials) {
      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
    }

    const nonce = await randomBytes(24);
    // store the nonce for later use
    authContext.nonce = nonce;

    const request = {
      ...handshakeDoc,
      speculativeAuthenticate: {
        ...makeFirstMessage(cryptoMethod, credentials, nonce),
        db: credentials.source
      }
    };

    return request;
  }

  override async auth(authContext: AuthContext) {

View on GitHub (pinned to dce7939f86)