mongodb/node-mongodb-native · error · MongoInvalidArgumentError

AuthMechanism '${credentials.mechanism}' not supported

Error message

AuthMechanism '${credentials.mechanism}' not supported

What it means

Thrown during performInitialHandshake when credentials are supplied but the credentials.mechanism is neither 'MONGODB-CR' (the default placeholder) nor a mechanism registered in the AuthProviders map. It is a client-side validation guard that runs before the first hello/auth round trip, so the connection never reaches the server with the bad mechanism.

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 3366c21a63)

Solutions

  1. Verify the authMechanism value exactly matches one of the supported constants in src/cmap/auth/providers.ts (e.g. 'SCRAM-SHA-256', 'SCRAM-SHA-1', 'MONGODB-X509', 'GSSAPI', 'PLAIN', 'MONGODB-AWS', 'MONGODB-OIDC').
  2. Drop the authMechanism option entirely to let the driver negotiate SCRAM-SHA-256/SCRAM-SHA-1 automatically.
  3. If using GSSAPI/AWS/OIDC, install the required optional dependency (kerberos / aws-sdk / the OIDC callback) and confirm it loads.
  4. Double-check there are no stray whitespace or case differences in the URI parameter.

Example fix

// before
const client = new MongoClient('mongodb://u:p@h/?authMechanism=scram-sha256'); // lowercase typo

// after
const client = new MongoClient('mongodb://u:p@h/?authMechanism=SCRAM-SHA-256');
Defensive patterns

Strategy: validation

Validate before calling

import { AuthMechanism } from 'mongodb';
const SUPPORTED = new Set<string>(Object.values(AuthMechanism));
function validateMechanism(m: string) {
  if (m !== 'MONGODB-CR' /* default placeholder */ && !SUPPORTED.has(m)) {
    throw new Error(`Unsupported authMechanism: ${m}. Supported: ${[...SUPPORTED].join(', ')}`);
  }
}

Type guard

import { AuthMechanism } from 'mongodb';
function isSupportedMechanism(m: string): boolean {
  return m === AuthMechanism.MONGODB_DEFAULT ||
    Object.values(AuthMechanism).includes(m as AuthMechanism);
}

Try / catch

import { MongoInvalidArgumentError } from 'mongodb';
try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /not supported/.test(e.message)) {
    // fix the URI authMechanism and recreate the client
  }
  throw e;
}

Prevention

When it happens

Trigger: Constructing MongoClient with an authMechanism URI option or credentials object whose value is misspelled or unsupported (e.g. 'SCRAM-SHA-1A', 'GSSAPI2', 'ldap', or any random string). Fires on the first operation that opens a connection (or on connect()) inside performInitialHandshake (src/cmap/connect.ts:96-105).

Common situations: Typo in the authMechanism URI parameter; copying a mechanism name from a different driver's docs (e.g. Java's 'MONGODB-X509' vs the value expected here); using a mechanism the driver only supports via an optional dependency that isn't installed (e.g. 'GSSAPI' without the kerberos package, 'MONGODB-AWS' without aws-sdk); upgrading the driver and passing a mechanism name that was renamed.

Related errors

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