What causes "${name} must be an object with 'username' and 'password' properties" in mongodb/node-mongodb-native?

Pass `auth` as `{ username: string, password: string }` — both keys required, spelled exactly `username` and `password`.

mongodb/node-mongodb-native · error · MongoParseError

must be an object with 'username' and 'password' properties

Error message

${name} must be an object with 'username' and 'password' properties

What it means

Thrown by MongoParseError at src/connection_string.ts:661 in the `auth` option transform when the value passed as `auth` is not an object containing both `username` and `password` properties (checked via `isRecord(value, ['username','password'])`). `${name}` is `auth`.

Solutions

Pass `auth` as `{ username: string, password: string }` — both keys required, spelled exactly `username` and `password`.
If you only need credentials, prefer the URI form `mongodb://username:password@host/` which fills the same fields.

Example fix

// before
new MongoClient(uri, { auth: { user: 'bob', password: 'secret' } })

// after
new MongoClient(uri, { auth: { username: 'bob', password: 'secret' } })

Defensive patterns

Strategy: type-guard

Validate before calling

function isValidAuth(v) { return v != null && typeof v === 'object' && !Array.isArray(v) && 'username' in v && 'password' in v; }

Type guard

function isAuthObject(v): v is { username: string; password: string } { return !!v && typeof v === 'object' && !Array.isArray(v) && typeof v.username === 'string' && typeof v.password === 'string'; }

Try / catch

try { new MongoClient(uri, { auth }); } catch (e) { if (e instanceof MongoParseError && /must be an object with 'username' and 'password'/.test(e.message)) { auth = { username: auth.user ?? auth.username, password: auth.pass ?? auth.password }; } else throw e; }

Prevention

Use the exact keys `username` and `password` (not `user`/`pass`).
Prefer the URI form `mongodb://user:pass@host/` to avoid key-name typos.

When it happens

Trigger: `new MongoClient(uri, { auth: 'bob' })`, `{ auth: { user: 'bob' } }` (wrong key), `{ auth: ['bob','pass'] }`, or omitting one of the two fields.

Common situations: Using `user` instead of `username` (a very common typo because other APIs use `user`); passing only username when password is also required by the option schema.

Related errors

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

Appendix: source

Thrown at src/connection_string.ts:661

   * @param options - the options so far for resolution
   * @param values - the possible values in precedence order
   */
  transform?: (args: { name: string; options: MongoOptions; values: unknown[] }) => unknown;
}

export const OPTIONS = {
  enableOverloadRetargeting: {
    default: false,
    type: 'boolean'
  },
  appName: {
    type: 'string'
  },
  auth: {
    target: 'credentials',
    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;

View on GitHub (pinned to dce7939f86)