mongodb/node-mongodb-native · error · MongoParseError

authMechanism one of ${mechanisms}, got ${value}

Error message

authMechanism one of ${mechanisms}, got ${value}

What it means

The `authMechanism` option must match one of the `AuthMechanism` enum values (DEFAULT, GSSAPI, PLAIN, SCRAM-SHA-1, SCRAM-SHA-256, MONGODB-X509, MONGODB-AWS, MONGODB-OIDC). The transform (src/connection_string.ts:671-698) matches the value case-insensitively as a word boundary inside each enum value; if no enum value contains it, it throws.

Source

Thrown at src/connection_string.ts:677

    transform({ name, options, values: [value] }): MongoCredentials {
      if (!isRecord(value, ['username', 'password'] as const)) {
        throw new MongoParseError(
          `${name} must be an object with 'username' and 'password' properties`
        );
      }
      return MongoCredentials.merge(options.credentials, {
        username: value.username,
        password: value.password
      });
    }
  },
  authMechanism: {
    target: 'credentials',
    transform({ options, values: [value] }): MongoCredentials {
      const mechanisms = Object.values(AuthMechanism);
      const [mechanism] = mechanisms.filter(m => m.match(RegExp(String.raw`\b${value}\b`, 'i')));
      if (!mechanism) {
        throw new MongoParseError(`authMechanism one of ${mechanisms}, got ${value}`);
      }
      let source = options.credentials?.source;
      if (
        mechanism === AuthMechanism.MONGODB_PLAIN ||
        AUTH_MECHS_AUTH_SRC_EXTERNAL.has(mechanism)
      ) {
        // some mechanisms have '$external' as the Auth Source
        source = '$external';
      }

      let password = options.credentials?.password;
      if (mechanism === AuthMechanism.MONGODB_X509 && password === '') {
        password = undefined;
      }
      return MongoCredentials.merge(options.credentials, {
        mechanism,
        source,
        password

View on GitHub (pinned to 3366c21a63)

Solutions

1. Use an exact AuthMechanism value: 'SCRAM-SHA-256', 'SCRAM-SHA-1', 'MONGODB-X509', 'MONGODB-AWS', 'MONGODB-OIDC', 'PLAIN', 'GSSAPI', or 'DEFAULT'
2. For LDAP, use 'PLAIN'
3. Omit authMechanism to let the driver negotiate SCRAM-SHA-1/256 automatically

Example fix

// before
new MongoClient(uri, { authMechanism: 'LDAP', authSource: '$external' });
// after
new MongoClient(uri, { authMechanism: 'PLAIN', authSource: '$external' });

import { AuthMechanism } from 'mongodb';
const VALID = new Set(Object.values(AuthMechanism));
function isValidMechanism(v) {
  return typeof v === 'string' && [...VALID].some(m => new RegExp(`\\b${v}\\b`, 'i').test(m));
}
if (options.authMechanism && !isValidMechanism(options.authMechanism)) {
  throw new TypeError(`Invalid authMechanism: ${options.authMechanism}`);
}

import { AuthMechanism } from 'mongodb';
function isAuthMechanism(v) {
  return Object.values(AuthMechanism).includes(v);
}

When it happens

Trigger: `{ authMechanism: 'LDAP' }` (LDAP uses 'PLAIN'); `{ authMechanism: 'scram' }` (ambiguous — must be exactly 'SCRAM-SHA-1' or 'SCRAM-SHA-256'); typos like 'MONGODB-AWS-OLD' or 'X509'.

Common situations: Confusing mechanism names with auth-source names; treating LDAP and PLAIN as distinct mechanisms; copy-paste typos; guessing that 'X509' alone works.

Related errors

• ${name} must be an object with 'username' and 'password' pro
• AuthMechanism '${credentials.mechanism}' not supported
• Descriptors missing a type must define a transform
• AuthMechanismProperties must be an object
• Invalid `serverApi` property; must specify a version from th

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