mongodb/node-mongodb-native · error · MongoMissingCredentialsError

AuthContext must provide credentials.

Error message

AuthContext must provide credentials.

What it means

Thrown by the PLAIN (LDAP) auth provider when the AuthContext has no credentials at the start of authentication (src/cmap/auth/plain.ts:9). MONGODB-PLAIN forwards a username and password to the server's LDAP backend via the SASL PLAIN mechanism. Surfaced as a MongoMissingCredentialsError.

Source

Thrown at src/cmap/auth/plain.ts:10

import { Binary, ByteUtils } from '../../bson';
import { MongoMissingCredentialsError } from '../../error';
import { ns } from '../../utils';
import { type AuthContext, AuthProvider } from './auth_provider';

export class Plain extends AuthProvider {
  override async auth(authContext: AuthContext): Promise<void> {
    const { connection, credentials } = authContext;
    if (!credentials) {
      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
    }

    const { username, password } = credentials;

    const payload = new Binary(ByteUtils.fromUTF8(`\x00${username}\x00${password}`));
    const command = {
      saslStart: 1,
      mechanism: 'PLAIN',
      payload: payload,
      autoAuthorize: 1
    };

    await connection.command(ns('$external.$cmd'), command, undefined);
  }
}

View on GitHub (pinned to 3366c21a63)

Solutions

1. Provide username and password in the connection string with authMechanism=PLAIN and authSource=$external.
2. Ensure the credentials are URL-encoded if they contain special characters.
3. Confirm the LDAP backend on the MongoDB server is configured and the user exists in the directory.
4. Verify the driver is using authSource=$external (PLAIN/LDAP always uses $external).

Example fix

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

// after
const c = new MongoClient(
  'mongodb://ldapuser:ldappass@host/?authMechanism=PLAIN&authSource=%24external'
);

function validatePlainCredentials(uri: string): void {
  if (!/authMechanism=PLAIN/i.test(uri)) return;
  if (!/(\/\/)[^:\/]+:[^@]+@/.test(uri)) {
    throw new Error('PLAIN (LDAP) auth requires username:password in the connection string');
  }
  if (!/authSource=%24external|authSource=\$external/i.test(uri)) {
    console.warn('PLAIN auth should use authSource=$external');
  }
}
validatePlainCredentials(connectionString);

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoMissingCredentialsError && /AuthContext must provide credentials/.test(e.message) && mechanism === 'PLAIN') {
    throw new Error('LDAP/PLAIN auth requires username and password (authSource=$external).');
  }
  throw e;
}

When it happens

Trigger: Connecting with authMechanism=PLAIN but omitting username and/or password, or when the credential merge step yields no credentials object. The PLAIN provider immediately checks for credentials and throws before sending the saslStart command.

Common situations: Forgot to include username/password in the URI when using LDAP auth, set them as empty strings, or pointed at $external auth source with no creds. Also common when the connection string parser did not pick up the credentials due to URL-encoding issues.

Related errors

• PLAIN Authentication Mechanism needs an auth source
• Username required for mechanism '${this.mechanism}'
• username and ENVIRONMENT '${this.mechanismProperties.ENVIRON
• No password is allowed in ENVIRONMENT '${this.mechanismPrope
• Invalid source '${this.source}' for mechanism '${this.mechan

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