{"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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/connection_string.ts#L386-L422","documentation":"Thrown when MONGODB-GSSAPI (Kerberos) or MONGODB-X509 auth is used and an authSource is explicitly provided but is not '$external'. External auth mechanisms require the special $external database; any other explicit authSource is rejected (connection_string.ts:398-407). If authSource is omitted, the driver defaults correctly, so this only fires on a wrong explicit value.","triggerScenarios":"URI like 'mongodb://user@host/?authMechanism=MONGODB-X509&authSource=admin' or options { authMechanism: 'MONGODB-GSSAPI', authSource: 'admin' }. Setting authSource to anything other than $external with GSSAPI/X509 triggers it.","commonSituations":"Reusing a SCRAM-SHA-256 connection template (authSource=admin) for an X509 deployment; configuring Kerberos and assuming the auth database is the application database.","solutions":["Remove the explicit authSource so the driver defaults to $external.","Or set authSource='$external' explicitly if you must specify it.","Verify the auth mechanism spelling (MONGODB-GSSAPI / MONGODB-X509)."],"exampleFix":"// before\nconst c = new MongoClient('mongodb://cn=user@host/?authMechanism=MONGODB-X509&authSource=admin');\n// after\nconst c = new MongoClient('mongodb://cn=user@host/?authMechanism=MONGODB-X509&authSource=$external');","handlingStrategy":"validation","validationCode":"const externalMechs = new Set(['MONGODB-GSSAPI', 'MONGODB-X509']);\nconst mech = opts.authMechanism ?? new URL(uri).searchParams.get('authMechanism');\nconst src = opts.authSource ?? new URL(uri).searchParams.get('authSource');\nif (externalMechs.has(mech ?? '') && src && src !== '$external') {\n  throw new Error(`authSource for ${mech} must be '$external' (got '${src}')`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When using GSSAPI/X509, omit authSource entirely and let the driver default.","Keep external-mechanism connection strings in a dedicated config section."],"tags":["connection-string","auth","x509","kerberos"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}