mongodb/node-mongodb-native · error · MongoParseError

authMechanism ${mongoOptions.credentials.mechanism} requires

Error message

authMechanism ${mongoOptions.credentials.mechanism} requires an authSource of '$external'

What it means

Thrown when MONGODB-GSSAPI (Kerberos) or MONGODB-X509 auth is used and an authSource is explicitly provided but is not '$external'. External auth mechanisms require the special $external database; any other explicit authSource is rejected (connection_string.ts:398-407). If authSource is omitted, the driver defaults correctly, so this only fires on a wrong explicit value.

Source

Thrown at src/connection_string.ts:404

        emitWarning(`${key} is a deprecated option${deprecatedMsg}`);
      }

      setOption(mongoOptions, key, descriptor, values);
    }
  }

  if (mongoOptions.credentials) {
    const isGssapi = mongoOptions.credentials.mechanism === AuthMechanism.MONGODB_GSSAPI;
    const isX509 = mongoOptions.credentials.mechanism === AuthMechanism.MONGODB_X509;
    const isAws = mongoOptions.credentials.mechanism === AuthMechanism.MONGODB_AWS;
    const isOidc = mongoOptions.credentials.mechanism === AuthMechanism.MONGODB_OIDC;
    if (
      (isGssapi || isX509) &&
      allProvidedOptions.has('authSource') &&
      mongoOptions.credentials.source !== '$external'
    ) {
      // If authSource was explicitly given and its incorrect, we error
      throw new MongoParseError(
        `authMechanism ${mongoOptions.credentials.mechanism} requires an authSource of '$external'`
      );
    }

    if (
      !(isGssapi || isX509 || isAws || isOidc) &&
      mongoOptions.dbName &&
      !allProvidedOptions.has('authSource')
    ) {
      // inherit the dbName unless GSSAPI or X509, then silently ignore dbName
      // and there was no specific authSource given
      mongoOptions.credentials = MongoCredentials.merge(mongoOptions.credentials, {
        source: mongoOptions.dbName
      });
    }

    if (isAws) {
      const { username, password } = mongoOptions.credentials;

View on GitHub (pinned to 3366c21a63)

Solutions

1. Remove the explicit authSource so the driver defaults to $external.
2. Or set authSource='$external' explicitly if you must specify it.
3. Verify the auth mechanism spelling (MONGODB-GSSAPI / MONGODB-X509).

Example fix

// before
const c = new MongoClient('mongodb://cn=user@host/?authMechanism=MONGODB-X509&authSource=admin');
// after
const c = new MongoClient('mongodb://cn=user@host/?authMechanism=MONGODB-X509&authSource=$external');

const externalMechs = new Set(['MONGODB-GSSAPI', 'MONGODB-X509']);
const mech = opts.authMechanism ?? new URL(uri).searchParams.get('authMechanism');
const src = opts.authSource ?? new URL(uri).searchParams.get('authSource');
if (externalMechs.has(mech ?? '') && src && src !== '$external') {
  throw new Error(`authSource for ${mech} must be '$external' (got '${src}')`);
}

When it happens

Trigger: URI like 'mongodb://user@host/?authMechanism=MONGODB-X509&authSource=admin' or options { authMechanism: 'MONGODB-GSSAPI', authSource: 'admin' }. Setting authSource to anything other than $external with GSSAPI/X509 triggers it.

Common situations: Reusing a SCRAM-SHA-256 connection template (authSource=admin) for an X509 deployment; configuring Kerberos and assuming the auth database is the application database.

Related errors

• Credentials required for GSSAPI authentication
• Invalid source '${this.source}' for mechanism '${this.mechan
• Password not allowed for mechanism MONGODB-X509
• Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}
• AuthContext must provide credentials.

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