mongodb/node-mongodb-native · error · MongoParseError

authMechanism requires an authSource of '$external

Error message

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

What it means

The GSSAPI (Kerberos) and MONGODB-X509 auth mechanisms require an external identity provider and must use authSource='$external'. If the caller explicitly sets authSource to anything else alongside one of these mechanisms, the driver refuses rather than silently misroute credentials. The check only fires when authSource was explicitly provided.

Solutions

1. Set authSource=$external when using GSSAPI or X509.
2. Or omit authSource entirely so the driver defaults to $external for these mechanisms.

Example fix

// before
new MongoClient('mongodb://user@h/db?authMechanism=GSSAPI&authSource=admin');
// after
new MongoClient('mongodb://user@h/db?authMechanism=GSSAPI&authSource=$external');

const EXTERNAL_MECHS = new Set(['GSSAPI', 'MONGODB-X509']);
function assertAuthSourceCompatible(mechanism: string, authSource?: string) {
  if (EXTERNAL_MECHS.has(mechanism) && authSource != null && authSource !== '$external') {
    throw new Error(`${mechanism} requires authSource=$external`);
  }
}

When it happens

Trigger: new MongoClient('mongodb://user@h/db?authMechanism=GSSAPI&authSource=admin') or the X509 equivalent with a non-$external authSource. Reached after credentials are assembled in parseOptions.

Common situations: Reusing a SCRAM-style connection string (authSource=admin) and just swapping authMechanism to GSSAPI/X509, or copying an X.509 example into an existing admin-auth URI.

Related errors

• Auth mechanism property ALLOWED_HOSTS is not allowed in the…
• Cannot have undefined values in key value pairs
• All values of tls/ssl must be the same.
• Cannot combine replicaSet option with srvMaxHosts
• Cannot have empty URI params in DNS TXT Record

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/09e95629bcb23664. Report an issue: GitHub.

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