mongodb/node-mongodb-native · error · MongoAPIError

Invalid source ' ' for mechanism ' ' specified.

Error message

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

What it means

Thrown by MongoCredentials.validate() when an external-source auth mechanism (GSSAPI, MONGODB-AWS, MONGODB-OIDC, MONGODB-X509) is configured with an authSource other than '$external'. These mechanisms always authenticate against the '$external' database, so any other source is invalid.

Solutions

1. Remove the authSource parameter, or set it explicitly to '$external'.
2. For these mechanisms, do not specify a source at all and let the driver default correctly.
3. Audit your connection string/template for stray authSource values.

Example fix

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

const EXTERNAL_MECHS = ['GSSAPI','MONGODB-AWS','MONGODB-OIDC','MONGODB-X509'];
function assertExternalSource(mech, source) {
  if (EXTERNAL_MECHS.includes(mech) && source != null && source !== '$external') {
    throw new Error(`authSource must be $external for ${mech}`);
  }
}

When it happens

Trigger: Setting authSource=<db> in the connection string or credentials while using GSSAPI/AWS/OIDC/X509. Fires in validate() via the AUTH_MECHS_AUTH_SRC_EXTERNAL set check.

Common situations: Carrying over authSource=admin from a SCRAM connection string. Explicitly setting source:'admin' in code. Tools/generators that auto-append authSource.

Related errors

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

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