{"id":"729719249f24415f","repo":"mongodb/node-mongodb-native","slug":"name-must-be-an-object-with-username-and-pas","errorCode":null,"errorMessage":"${name} must be an object with 'username' and 'password' properties","messagePattern":"(.+?) must be an object with 'username' and 'password' properties","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":661,"sourceCode":"   * @param options - the options so far for resolution\n   * @param values - the possible values in precedence order\n   */\n  transform?: (args: { name: string; options: MongoOptions; values: unknown[] }) => unknown;\n}\n\nexport const OPTIONS = {\n  enableOverloadRetargeting: {\n    default: false,\n    type: 'boolean'\n  },\n  appName: {\n    type: 'string'\n  },\n  auth: {\n    target: 'credentials',\n    transform({ name, options, values: [value] }): MongoCredentials {\n      if (!isRecord(value, ['username', 'password'] as const)) {\n        throw new MongoParseError(\n          `${name} must be an object with 'username' and 'password' properties`\n        );\n      }\n      return MongoCredentials.merge(options.credentials, {\n        username: value.username,\n        password: value.password\n      });\n    }\n  },\n  authMechanism: {\n    target: 'credentials',\n    transform({ options, values: [value] }): MongoCredentials {\n      const mechanisms = Object.values(AuthMechanism);\n      const [mechanism] = mechanisms.filter(m => m.match(RegExp(String.raw`\\b${value}\\b`, 'i')));\n      if (!mechanism) {\n        throw new MongoParseError(`authMechanism one of ${mechanisms}, got ${value}`);\n      }\n      let source = options.credentials?.source;","sourceCodeStart":643,"sourceCodeEnd":679,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/connection_string.ts#L643-L679","documentation":"The `auth` option lets you supply credentials as an object, but the driver requires it to be a plain object containing both `username` and `password` keys. The transform (src/connection_string.ts:657-669) calls `isRecord(value, ['username','password'])`; if either key is missing or the value is not an object, it throws a MongoParseError.","triggerScenarios":"`new MongoClient(uri, { auth: 'user:pass' })` (string); `{ auth: { username: 'x' } }` (password missing); `{ auth: null }`; `{ auth: ['u','p'] }` (array is not a record).","commonSituations":"Migrating from a config that stores credentials as a single string; env-var parsing that drops undefined keys; spreading a partial credentials object.","solutions":["Provide auth as `{ username: 'u', password: 'p' }`","Put credentials in the URI instead: mongodb://username:password@host/db","Use separate `authSource`/`authMechanism` options rather than overloading `auth`"],"exampleFix":"// before\nnew MongoClient(uri, { auth: 'user:pass' });\n// after\nnew MongoClient(uri, { auth: { username: 'user', password: 'pass' } });\n// or\nnew MongoClient('mongodb://user:pass@host/db');","handlingStrategy":"type-guard","validationCode":"function isValidAuth(value) {\n  return (\n    value != null &&\n    typeof value === 'object' &&\n    !Array.isArray(value) &&\n    'username' in value &&\n    'password' in value\n  );\n}\nif (options.auth && !isValidAuth(options.auth)) {\n  throw new TypeError('auth must be { username, password }');\n}","typeGuard":"function isAuthObject(v) {\n  return (\n    !!v &&\n    typeof v === 'object' &&\n    !Array.isArray(v) &&\n    typeof v.username === 'string' &&\n    typeof v.password === 'string'\n  );\n}","tryCatchPattern":"try {\n  const client = new MongoClient(uri, options);\n} catch (e) {\n  if (e instanceof MongoParseError && /must be an object with 'username' and 'password'/.test(e.message)) {\n    // fix credentials shape and retry\n  } else throw e;\n}","preventionTips":["Always pass credentials as an object with both username and password","Prefer encoding credentials in the connection URI","Validate env-derived credential objects before constructing the client"],"tags":["authentication","configuration","options"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}