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 by MongoCredentials.validate() when MONGODB-PLAIN is used but no auth source is supplied. PLAIN (LDAP) authentication is not performed against the default 'admin' database in many deployments, so the driver requires an explicit source to know where to send credentials.

Solutions

1. Add authSource to the connection string (commonly '$external' for LDAP).
2. In code, pass credentials with source:'$external' (or your LDAP auth database).
3. Confirm with your LDAP/MongoDB admin which database PLAIN auth targets.

Example fix

// before
new MongoClient(url, { auth: { mechanism:'PLAIN', username:'u', password:'p' } });
// after
new MongoClient(url, { auth: { mechanism:'PLAIN', username:'u', password:'p', source:'$external' } });

function assertPlainSource(mech, source) {
  if (mech === 'PLAIN' && source == null) {
    throw new Error('MONGODB-PLAIN requires an authSource (often $external).');
  }
}

When it happens

Trigger: Configuring authMechanism='PLAIN' without an authSource (and no default resolves). Fires at validate() line 261 where this.source == null.

Common situations: Setting up LDAP/PLAIN auth and forgetting authSource. The connection string lacks authSource and no db fallback applies.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• AuthContext must provide credentials.
• Invalid source ' ' for mechanism ' ' specified.
• Auth mechanism property ALLOWED_HOSTS must be an array of…
• 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/a60c261c24298fcc. Report an issue: GitHub.

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