mongodb/node-mongodb-native · error · MongoInvalidArgumentError

authMechanism not supported

Error message

authMechanism ${name} not supported

What it means

Thrown when the credentials' authMechanism is not one of the registered providers (MONGODB-AWS, MONGODB-GSSAPI, MONGODB-OIDC, MONGODB-PLAIN, MONGODB-SCRAM-SHA1, MONGODB-SCRAM-SHA256, MONGODB-X509). The driver looks the name up in its AUTH_PROVIDERS map at first authentication and refuses to proceed with an unknown mechanism.

Solutions

1. Use one of the supported mechanism strings exactly: 'MONGODB-AWS', 'MONGODB-GSSAPI', 'MONGODB-OIDC', 'MONGODB-PLAIN', 'MONGODB-SCRAM-SHA1', 'MONGODB-SCRAM-SHA256', 'MONGODB-X509'.
2. If using SCRAM, prefer the default (omit authMechanism) so the driver negotiates SCRAM-SHA-256 automatically.
3. For Kerberos/LDAP, remember the driver exposes them as MONGODB-GSSAPI and MONGODB-PLAIN respectively.

Example fix

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

// after
const client = new MongoClient('mongodb://u:p@h/'); // driver picks SCRAM-SHA-256
// or explicit:
const client = new MongoClient('mongodb://u:p@h/?authMechanism=MONGODB-SCRAM-SHA256');

const SUPPORTED = new Set([
  'MONGODB-AWS', 'MONGODB-GSSAPI', 'MONGODB-OIDC',
  'MONGODB-PLAIN', 'MONGODB-SCRAM-SHA1',
  'MONGODB-SCRAM-SHA256', 'MONGODB-X509'
]);
if (mechanism && !SUPPORTED.has(mechanism.toUpperCase())) {
  throw new Error(`Unsupported authMechanism: ${mechanism}`);
}

import { AuthMechanism } from 'mongodb';
const isAuthMechanism = (v: string): v is AuthMechanism =>
  Object.values(AuthMechanism).includes(v as AuthMechanism);

try {
  await client.connect();
} catch (e) {
  if (/authMechanism .* not supported/.test(e.message)) {
    // fix the connection string and retry with a new client
  }
  throw e;
}

When it happens

Trigger: Passing a misspelled or unsupported authMechanism in the connection string (e.g. ?authMechanism=SCRAM-SHA-256) or in MongoClient options credentials.mechanism. Also triggered by using a custom mechanism name without registering a provider.

Common situations: Connection-string typos (hyphens vs. underscores, wrong casing, version suffixes like -256); copying credentials between projects with different driver versions; assuming a mechanism like 'LDAP' exists when the driver only exposes MONGODB-PLAIN for LDAP.

Related errors

• authMechanism one of
• AuthMechanismProperties must be an object
• AWS_SESSION_TOKEN cannot be provided when using…
• Could not load workflow for environment
• must be an object with 'username' and 'password' properties

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

Appendix: source

Thrown at src/mongo_client_auth_providers.ts:60

   * We don't want to create all providers at once, as some providers may not be used.
   * @param name - The name of the provider to get or create.
   * @param credentials - The credentials.
   * @returns The provider.
   * @throws MongoInvalidArgumentError if the mechanism is not supported.
   * @internal
   */
  getOrCreateProvider(
    name: AuthMechanism | string,
    authMechanismProperties: AuthMechanismProperties
  ): AuthProvider {
    const authProvider = this.existingProviders.get(name);
    if (authProvider) {
      return authProvider;
    }

    const providerFunction = AUTH_PROVIDERS.get(name);
    if (!providerFunction) {
      throw new MongoInvalidArgumentError(`authMechanism ${name} not supported`);
    }

    const provider = providerFunction(authMechanismProperties);
    this.existingProviders.set(name, provider);
    return provider;
  }
}

/**
 * Gets either a device workflow or callback workflow.
 */
function getWorkflow(authMechanismProperties: AuthMechanismProperties): Workflow {
  if (authMechanismProperties.OIDC_HUMAN_CALLBACK) {
    return new HumanCallbackWorkflow(new TokenCache(), authMechanismProperties.OIDC_HUMAN_CALLBACK);
  } else if (authMechanismProperties.OIDC_CALLBACK) {
    return new AutomatedCallbackWorkflow(new TokenCache(), authMechanismProperties.OIDC_CALLBACK);
  } else {
    const environment = authMechanismProperties.ENVIRONMENT;

View on GitHub (pinned to dce7939f86)