mongodb/node-mongodb-native · critical · MongoMissingCredentialsError

AuthContext must provide credentials.

Error message

AuthContext must provide credentials.

What it means

Thrown by the PLAIN (LDAP) auth provider (plain.ts:10) when the AuthContext has no credentials. PLAIN auth requires a username and password to build the SASL PLAIN payload (\x00username\x00password); without credentials the provider cannot construct it. Raised as MongoMissingCredentialsError.

Solutions

1. Include username and password in the URI: mongodb://user:pass@host/?authMechanism=PLAIN&authSource=$external
2. Pass credentials programmatically via MongoClient options if not in the URI
3. Confirm authSource=$external for LDAP/PLAIN deployments

Example fix

// before
const uri = 'mongodb://ldap-host/?authMechanism=PLAIN';

// after
const uri = 'mongodb://user:password@ldap-host/?authMechanism=PLAIN&authSource=$external';

if (clientOptions.auth?.mechanism === 'PLAIN') {
  const u = clientOptions.auth?.username;
  const p = clientOptions.auth?.password;
  if (typeof u !== 'string' || typeof p !== 'string' || u === '' || p === '') {
    throw new Error('PLAIN (LDAP) auth requires a username and password');
  }
}

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

try {
  await client.connect();
} catch (err) {
  if (err instanceof MongoMissingCredentialsError && /PLAIN|LDAP/.test(err.message)) {
    // prompt for LDAP creds and reconnect
  } else throw err;
}

When it happens

Trigger: Connecting with authMechanism=PLAIN (LDAP) but no username/password in the connection string or options, or the credentials object failed to materialize during handshake.

Common situations: Using mongodb://host:port/?authMechanism=PLAIN with no user:pass in the URI. LDAP/AD setup where credentials are expected from a separate env source but never wired into MongoClient. authSource misconfiguration causing credentials to drop.

Related errors

• PLAIN Authentication Mechanism needs an auth source
• AuthContext must provide credentials.
• AuthContext must provide credentials.
• AuthContext must provide credentials.
• AuthMechanism ' ' not supported

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

Appendix: 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 dce7939f86)