What causes "authMechanism one of ${mechanisms}, got ${value}" in mongodb/node-mongodb-native?

mongodb/node-mongodb-native · error · MongoParseError

authMechanism one of

Error message

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

What it means

Thrown by MongoParseError at src/connection_string.ts:677 in the `authMechanism` transform when the supplied value does not match (case-insensitive whole-word) any entry of the `AuthMechanism` enum: MONGODB-AWS, DEFAULT, GSSAPI, PLAIN, SCRAM-SHA-1, SCRAM-SHA-256, MONGODB-X509, MONGODB-OIDC. The error message lists the accepted values and echoes the bad value.

Solutions

Use one of the exact enum values: MONGODB-AWS, DEFAULT, GSSAPI, PLAIN, SCRAM-SHA-1, SCRAM-SHA-256, MONGODB-X509, MONGODB-OIDC (case-insensitive).
If using the options object, import the AuthMechanism enum and reference it: `authMechanism: AuthMechanism.MONGODB_X509`.
Re-read the error message — it lists every valid value.

Example fix

// before
new MongoClient('mongodb://host/?authMechanism=SCRAM-SHA256')

// after
new MongoClient('mongodb://host/?authMechanism=SCRAM-SHA-256')

Defensive patterns

Strategy: validation

Validate before calling

const VALID = new Set(['MONGODB-AWS','DEFAULT','GSSAPI','PLAIN','SCRAM-SHA-1','SCRAM-SHA-256','MONGODB-X509','MONGODB-OIDC']);
function assertValidMechanism(value) { if (!VALID.has(String(value).toUpperCase())) throw new Error(`authMechanism must be one of ${[...VALID].join(', ')}`); }

Type guard

import { AuthMechanism } from 'mongodb';
function isAuthMechanism(v): v is AuthMechanism { return Object.values(AuthMechanism).some(m => new RegExp(`\\b${v}\\b`, 'i').test(m)); }

Try / catch

try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoParseError && /authMechanism one of/.test(e.message)) { options.authMechanism = 'SCRAM-SHA-256'; } else throw e; }

Prevention

Import the AuthMechanism enum from 'mongodb' and reference its members rather than typing strings.
Cross-check spelling against the error message, which enumerates every valid value.

When it happens

Trigger: `?authMechanism=SCRAM-SHA256` (missing hyphen), `?authMechanism=aws`, `?authMechanism=LDAP`, or `{ authMechanism: 'mongo-db-x509' }`.

Common situations: Misspelling SCRAM-SHA-256 as SCRAM-SHA256; using 'aws' instead of 'MONGODB-AWS'; copying examples from older docs that name mechanisms differently; case/formatting typos.

Related errors

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

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