mongodb/node-mongodb-native · error · MongoAPIError

Invalid source '${this.source}' for mechanism '${this.mechan

Error message

Invalid source '${this.source}' for mechanism '${this.mechanism}' specified.

What it means

Thrown when an explicit authSource is set to anything other than '$external' for a mechanism that uses the external database (GSSAPI, AWS, OIDC, X509). These mechanisms always authenticate against '$external'; specifying 'admin' or any db name is invalid. The driver surfaces this as a MongoAPIError during credential validation.

Source

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

      }

      if (this.mechanismProperties.ALLOWED_HOSTS) {
        const hosts = this.mechanismProperties.ALLOWED_HOSTS;
        if (!Array.isArray(hosts)) {
          throw new MongoInvalidArgumentError(ALLOWED_HOSTS_ERROR);
        }
        for (const host of hosts) {
          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`);
    }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Remove authSource for these mechanisms, or set it explicitly to '$external'.
2. Update connection string to '.../?authMechanism=MONGODB-X509&authSource=$external'.
3. Fix any infra config templating that hard-codes authSource=admin.

Example fix

// before
'mongodb://host/?authMechanism=MONGODB-X509&authSource=admin'

// after
'mongodb://host/?authMechanism=MONGODB-X509&authSource=$external'

const EXTERNAL_MECHS = new Set(['GSSAPI','MONGODB-AWS','MONGODB-OIDC','MONGODB-X509']);
function validateAuthSource(mechanism: string, source?: string) {
  if (EXTERNAL_MECHS.has(mechanism) && source && source !== '$external') {
    throw new Error(`authSource must be '$external' for ${mechanism}`);
  }
}

import { MongoAPIError } from 'mongodb';
function isInvalidSource(e: unknown): boolean {
  return e instanceof MongoAPIError && /Invalid source/.test(e.message);
}

When it happens

Trigger: In MongoCredentials.validate() when AUTH_MECHS_AUTH_SRC_EXTERNAL.has(mechanism) and source is set and !== '$external'.

Common situations: Migrating a SCRAM connection string that had authSource=admin and just changing authMechanism to MONGODB-X509/GSSAPI/AWS/OIDC; setting authSource in code while forgetting the external rule; misconfigured ops template.

Related errors

• username and ENVIRONMENT '${this.mechanismProperties.ENVIRON
• No password is allowed in ENVIRONMENT '${this.mechanismPrope
• Password not allowed for mechanism MONGODB-X509
• AuthContext must provide credentials.
• Could not obtain temporary MONGODB-AWS credentials

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