{"record":{"id":"09e95629bcb23664","repo":"mongodb/node-mongodb-native","slug":"authmechanism-mongooptions-credentials-mechanism","errorCode":null,"errorMessage":"authMechanism ${mongoOptions.credentials.mechanism} requires an authSource of '$external'","messagePattern":"authMechanism (.+?) requires an authSource of '\\$external'","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":404,"sourceCode":"        emitWarning(`${key} is a deprecated option${deprecatedMsg}`);\n      }\n\n      setOption(mongoOptions, key, descriptor, values);\n    }\n  }\n\n  if (mongoOptions.credentials) {\n    const isGssapi = mongoOptions.credentials.mechanism === AuthMechanism.MONGODB_GSSAPI;\n    const isX509 = mongoOptions.credentials.mechanism === AuthMechanism.MONGODB_X509;\n    const isAws = mongoOptions.credentials.mechanism === AuthMechanism.MONGODB_AWS;\n    const isOidc = mongoOptions.credentials.mechanism === AuthMechanism.MONGODB_OIDC;\n    if (\n      (isGssapi || isX509) &&\n      allProvidedOptions.has('authSource') &&\n      mongoOptions.credentials.source !== '$external'\n    ) {\n      // If authSource was explicitly given and its incorrect, we error\n      throw new MongoParseError(\n        `authMechanism ${mongoOptions.credentials.mechanism} requires an authSource of '$external'`\n      );\n    }\n\n    if (\n      !(isGssapi || isX509 || isAws || isOidc) &&\n      mongoOptions.dbName &&\n      !allProvidedOptions.has('authSource')\n    ) {\n      // inherit the dbName unless GSSAPI or X509, then silently ignore dbName\n      // and there was no specific authSource given\n      mongoOptions.credentials = MongoCredentials.merge(mongoOptions.credentials, {\n        source: mongoOptions.dbName\n      });\n    }\n\n    if (isAws) {\n      const { username, password } = mongoOptions.credentials;","sourceCodeStart":386,"sourceCodeEnd":422,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/connection_string.ts#L386-L422","documentation":"The GSSAPI (Kerberos) and MONGODB-X509 auth mechanisms require an external identity provider and must use authSource='$external'. If the caller explicitly sets authSource to anything else alongside one of these mechanisms, the driver refuses rather than silently misroute credentials. The check only fires when authSource was explicitly provided.","triggerScenarios":"new MongoClient('mongodb://user@h/db?authMechanism=GSSAPI&authSource=admin') or the X509 equivalent with a non-$external authSource. Reached after credentials are assembled in parseOptions.","commonSituations":"Reusing a SCRAM-style connection string (authSource=admin) and just swapping authMechanism to GSSAPI/X509, or copying an X.509 example into an existing admin-auth URI.","solutions":["Set authSource=$external when using GSSAPI or X509.","Or omit authSource entirely so the driver defaults to $external for these mechanisms."],"exampleFix":"// before\nnew MongoClient('mongodb://user@h/db?authMechanism=GSSAPI&authSource=admin');\n// after\nnew MongoClient('mongodb://user@h/db?authMechanism=GSSAPI&authSource=$external');","handlingStrategy":"validation","validationCode":"const EXTERNAL_MECHS = new Set(['GSSAPI', 'MONGODB-X509']);\nfunction assertAuthSourceCompatible(mechanism: string, authSource?: string) {\n  if (EXTERNAL_MECHS.has(mechanism) && authSource != null && authSource !== '$external') {\n    throw new Error(`${mechanism} requires authSource=$external`);\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["For GSSAPI/X509, omit authSource or set it to $external.","Do not reuse SCRAM connection strings for external mechanisms."],"tags":["auth","connection-string","kerberos","x509","validation"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}