mongodb/node-mongodb-native · error · MongoInvalidArgumentError

AuthMechanism ' ' not supported

Error message

AuthMechanism '${credentials.mechanism}' not supported

What it means

Thrown as a MongoInvalidArgumentError in performInitialHandshake() when credentials are present and the mechanism is not MONGODB_DEFAULT, but authProviders.getOrCreateProvider(mechanism, mechanismProperties) returns null/undefined — meaning no provider class is registered for that auth mechanism. This is the early, pre-handshake check (before the server is even contacted).

Solutions

1. Correct the authMechanism spelling (valid: SCRAM-SHA-1, SCRAM-SHA-256, MONGODB-X509, MONGODB-AWS, MONGODB-OIDC, GSSAPI, PLAIN, MONGODB-CR-SESSION)
2. Install the optional dependency for the chosen mechanism (aws sdk, kerberos)
3. Omit authMechanism to let the driver and server negotiate (MONGODB_DEFAULT)

Example fix

// before
const client = new MongoClient('mongodb://host/db?authMechanism=SCRAM-SHA-512');

// after
const client = new MongoClient('mongodb://user:pass@host/db'); // let driver negotiate

const SUPPORTED = new Set(['SCRAM-SHA-1','SCRAM-SHA-256','MONGODB-X509','MONGODB-AWS','MONGODB-OIDC','GSSAPI','PLAIN','MONGODB-CR-SESSION','MONGODB-DEFAULT']);
const m = new URL(uri).searchParams.get('authMechanism');
if (m && !SUPPORTED.has(m.toUpperCase())) throw new Error(`Unsupported authMechanism: ${m}`);

function isSupportedMechanism(m: string): boolean {
  return ['SCRAM-SHA-1','SCRAM-SHA-256','MONGODB-X509','MONGODB-AWS','MONGODB-OIDC','GSSAPI','PLAIN','MONGODB-CR-SESSION'].includes(m);
}

When it happens

Trigger: Configuring an authMechanism the driver does not recognize (e.g. a typo like 'SCRAM-SHA-512', or a mechanism whose optional dependency is missing such as MONGODB-AWS without the aws sdk, MONGODB-CR which was removed, or PLAIN/GSSAPI without their libs). The check runs at the start of performInitialHandshake.

Common situations: Typo in the authMechanism query parameter; using MONGODB-AWS in an environment without @aws-sdk/credential-providers; requesting MONGODB-CR (removed in driver 4.0); requesting GSSAPI without the kerberos package installed.

Related errors

• AuthContext must provide credentials.
• AuthContext must provide credentials.
• AuthContext must provide credentials.
• AuthContext must provide credentials.
• Invalid source ' ' for mechanism ' ' specified.

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

Appendix: source

Thrown at src/cmap/connect.ts:104

  }, but this version of the Node.js Driver requires at least ${MIN_SUPPORTED_WIRE_VERSION} (MongoDB ${MIN_SUPPORTED_SERVER_VERSION})`;
  return new MongoCompatibilityError(message);
}

export async function performInitialHandshake(
  conn: Connection,
  options: ConnectionOptions
): Promise<void> {
  const credentials = options.credentials;

  if (credentials) {
    if (
      !(credentials.mechanism === AuthMechanism.MONGODB_DEFAULT) &&
      !options.authProviders.getOrCreateProvider(
        credentials.mechanism,
        credentials.mechanismProperties
      )
    ) {
      throw new MongoInvalidArgumentError(`AuthMechanism '${credentials.mechanism}' not supported`);
    }
  }

  const authContext = new AuthContext(conn, credentials, options);
  conn.authContext = authContext;

  // If we encounter an error preparing the handshake document, do NOT apply backpressure labels.  Errors
  // encountered building the handshake document are all client-side, and do not indicate an overloaded server.
  const handshakeDoc = await prepareHandshakeDocument(authContext);

  // @ts-expect-error: TODO(NODE-5141): The options need to be filtered properly, Connection options differ from Command options
  const handshakeOptions: CommandOptions = { ...options, raw: false };
  if (typeof options.connectTimeoutMS === 'number') {
    // The handshake technically is a monitoring check, so its socket timeout should be connectTimeoutMS
    handshakeOptions.socketTimeoutMS = options.connectTimeoutMS;
  }

  const start = new Date().getTime();

View on GitHub (pinned to dce7939f86)