{"id":"c18aa6ed5e972753","repo":"mongodb/node-mongodb-native","slug":"authmechanism-credentials-mechanism-not-suppo","errorCode":null,"errorMessage":"AuthMechanism '${credentials.mechanism}' not supported","messagePattern":"AuthMechanism '(.+?)' not supported","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/cmap/connect.ts","lineNumber":104,"sourceCode":"  }, but this version of the Node.js Driver requires at least ${MIN_SUPPORTED_WIRE_VERSION} (MongoDB ${MIN_SUPPORTED_SERVER_VERSION})`;\n  return new MongoCompatibilityError(message);\n}\n\nexport async function performInitialHandshake(\n  conn: Connection,\n  options: ConnectionOptions\n): Promise<void> {\n  const credentials = options.credentials;\n\n  if (credentials) {\n    if (\n      !(credentials.mechanism === AuthMechanism.MONGODB_DEFAULT) &&\n      !options.authProviders.getOrCreateProvider(\n        credentials.mechanism,\n        credentials.mechanismProperties\n      )\n    ) {\n      throw new MongoInvalidArgumentError(`AuthMechanism '${credentials.mechanism}' not supported`);\n    }\n  }\n\n  const authContext = new AuthContext(conn, credentials, options);\n  conn.authContext = authContext;\n\n  // If we encounter an error preparing the handshake document, do NOT apply backpressure labels.  Errors\n  // encountered building the handshake document are all client-side, and do not indicate an overloaded server.\n  const handshakeDoc = await prepareHandshakeDocument(authContext);\n\n  // @ts-expect-error: TODO(NODE-5141): The options need to be filtered properly, Connection options differ from Command options\n  const handshakeOptions: CommandOptions = { ...options, raw: false };\n  if (typeof options.connectTimeoutMS === 'number') {\n    // The handshake technically is a monitoring check, so its socket timeout should be connectTimeoutMS\n    handshakeOptions.socketTimeoutMS = options.connectTimeoutMS;\n  }\n\n  const start = new Date().getTime();","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cmap/connect.ts#L86-L122","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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').","Drop the authMechanism option entirely to let the driver negotiate SCRAM-SHA-256/SCRAM-SHA-1 automatically.","If using GSSAPI/AWS/OIDC, install the required optional dependency (kerberos / aws-sdk / the OIDC callback) and confirm it loads.","Double-check there are no stray whitespace or case differences in the URI parameter."],"exampleFix":"// before\nconst client = new MongoClient('mongodb://u:p@h/?authMechanism=scram-sha256'); // lowercase typo\n\n// after\nconst client = new MongoClient('mongodb://u:p@h/?authMechanism=SCRAM-SHA-256');","handlingStrategy":"validation","validationCode":"import { AuthMechanism } from 'mongodb';\nconst SUPPORTED = new Set<string>(Object.values(AuthMechanism));\nfunction validateMechanism(m: string) {\n  if (m !== 'MONGODB-CR' /* default placeholder */ && !SUPPORTED.has(m)) {\n    throw new Error(`Unsupported authMechanism: ${m}. Supported: ${[...SUPPORTED].join(', ')}`);\n  }\n}","typeGuard":"import { AuthMechanism } from 'mongodb';\nfunction isSupportedMechanism(m: string): boolean {\n  return m === AuthMechanism.MONGODB_DEFAULT ||\n    Object.values(AuthMechanism).includes(m as AuthMechanism);\n}","tryCatchPattern":"import { MongoInvalidArgumentError } from 'mongodb';\ntry {\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoInvalidArgumentError && /not supported/.test(e.message)) {\n    // fix the URI authMechanism and recreate the client\n  }\n  throw e;\n}","preventionTips":["Prefer letting the driver negotiate SCRAM by omitting authMechanism.","When you must specify it, type the value as AuthMechanism in TS so the compiler checks it.","Install optional auth deps (kerberos, aws-sdk) before using GSSAPI / AWS mechanisms."],"tags":["auth","authentication","configuration","handshake"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}