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) as a MongoMissingCredentialsError when the AuthContext has no credentials object at the start of the SCRAM handshake's speculative authentication phase. The driver needs username/password to build the first SCRAM message. This almost always indicates the connection string or credentials resolver did not supply authentication details for an auth-enabled deployment.

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

Solutions

1. Add username:password@ to the connection string: 'mongodb://user:pass@host:27017/?authSource=admin'
2. Verify the authSource matches where the user is defined (commonly 'admin' or '$external')
3. If using options.auth, pass a MongoCredentials-like object with username and password
4. Confirm environment variables (MONGODB_URI, DB_USER, DB_PASS) are loaded before MongoClient construction

Example fix

// before
const client = new MongoClient('mongodb://host:27017');
// after
const client = new MongoClient('mongodb://user:pass@host:27017/?authSource=admin');

function hasAuthCredentials(uri: string): boolean {
  try {
    const parsed = new URL(uri);
    return Boolean(parsed.username && parsed.password);
  } catch {
    return false;
  }
}
// before connect:
if (!hasAuthCredentials(process.env.MONGODB_URI!) && serverRequiresAuth) {
  throw new Error('MONGODB_URI missing username/password for auth-enabled deployment');
}

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

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoMissingCredentialsError) {
    // fix the connection string / auth option, then re-create the client
  }
  throw e;
}

When it happens

Trigger: Connecting with a URI that omits username/password (e.g. 'mongodb://host:27017') against a deployment with authentication enabled; or MongoClient.connect with an authMechanism=MONGODB-SCRAM-SHA-1|256 but a credentials callback that resolved undefined. Also fires if the AuthContext was constructed programmatically without a MongoCredentials instance.

Common situations: Switching from a no-auth local MongoDB to an auth-enabled Atlas/replica set without updating the URI; environment-specific credentials not loaded (e.g. dotenv not applied before connect); typo'd authSource that yields empty credentials; credentials provider returning undefined in multi-tenant setups.

Related errors

• Username required for mechanism '${this.mechanism}'
• Server returned an invalid signature
• Username must be a string
• Password must be a string
• Password cannot be empty

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