mongodb/node-mongodb-native · error · MongoAPIError

PLAIN Authentication Mechanism needs an auth source

Error message

PLAIN Authentication Mechanism needs an auth source

What it means

Thrown for the PLAIN (LDAP) auth mechanism when no authSource is provided. Unlike SCRAM, PLAIN does not default to 'admin'; the driver requires the caller to name the source database explicitly (commonly '$external' for LDAP). This is a MongoAPIError surfaced at validate() time.

Source

Thrown at src/cmap/auth/mongo_credentials.ts:261

          if (typeof host !== 'string') {
            throw new MongoInvalidArgumentError(ALLOWED_HOSTS_ERROR);
          }
        }
      }
    }

    if (AUTH_MECHS_AUTH_SRC_EXTERNAL.has(this.mechanism)) {
      if (this.source != null && this.source !== '$external') {
        // TODO(NODE-3485): Replace this with a MongoAuthValidationError
        throw new MongoAPIError(
          `Invalid source '${this.source}' for mechanism '${this.mechanism}' specified.`
        );
      }
    }

    if (this.mechanism === AuthMechanism.MONGODB_PLAIN && this.source == null) {
      // TODO(NODE-3485): Replace this with a MongoAuthValidationError
      throw new MongoAPIError('PLAIN Authentication Mechanism needs an auth source');
    }

    if (this.mechanism === AuthMechanism.MONGODB_X509 && this.password != null) {
      if (this.password === '') {
        Reflect.set(this, 'password', undefined);
        return;
      }
      // TODO(NODE-3485): Replace this with a MongoAuthValidationError
      throw new MongoAPIError(`Password not allowed for mechanism MONGODB-X509`);
    }

    const canonicalization = this.mechanismProperties.CANONICALIZE_HOST_NAME ?? false;
    if (!Object.values(GSSAPICanonicalizationValue).includes(canonicalization)) {
      throw new MongoAPIError(`Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}`);
    }
  }

  static merge(

View on GitHub (pinned to 3366c21a63)

Solutions

1. Add authSource=$external (most common for LDAP): 'mongodb://user:pass@host/?authMechanism=PLAIN&authSource=$external'.
2. Set the authSource to the LDAP-integrated database your deployment expects.
3. Confirm with the DBA which database backs LDAP auth.

Example fix

// before
'mongodb://user:pass@host/?authMechanism=PLAIN'

// after
'mongodb://user:pass@host/?authMechanism=PLAIN&authSource=$external'

function validatePlain(mechanism: string, source?: string) {
  if (mechanism === 'PLAIN' && source == null) {
    throw new Error('PLAIN requires authSource (usually $external)');
  }
}

import { MongoAPIError } from 'mongodb';
function isPlainNeedsSource(e: unknown): boolean {
  return e instanceof MongoAPIError && /PLAIN Authentication Mechanism needs an auth source/.test(e.message);
}

When it happens

Trigger: In MongoCredentials.validate() when mechanism === MONGODB_PLAIN and source == null.

Common situations: Using PLAIN/LDAP auth and forgetting authSource; assuming it defaults like SCRAM; connection string with no authSource and authMechanism=PLAIN.

Related errors

• AuthContext must provide credentials.
• 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/a60c261c24298fcc.json. Report an issue: GitHub.