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

Provide auth as `{ username: 'u', password: 'p' }`

mongodb/node-mongodb-native · error · MongoParseError

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

Error message

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

What it means

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.

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 3366c21a63)

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`

Example fix

// before
new MongoClient(uri, { auth: 'user:pass' });
// after
new MongoClient(uri, { auth: { username: 'user', password: 'pass' } });
// or
new MongoClient('mongodb://user:pass@host/db');

Defensive patterns

Strategy: type-guard

Validate before calling

function isValidAuth(value) {
  return (
    value != null &&
    typeof value === 'object' &&
    !Array.isArray(value) &&
    'username' in value &&
    'password' in value
  );
}
if (options.auth && !isValidAuth(options.auth)) {
  throw new TypeError('auth must be { username, password }');
}

Type guard

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

Try / catch

try {
  const client = new MongoClient(uri, options);
} catch (e) {
  if (e instanceof MongoParseError && /must be an object with 'username' and 'password'/.test(e.message)) {
    // fix credentials shape and retry
  } else throw e;
}

Prevention

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

When it happens

Trigger: `new MongoClient(uri, { auth: 'user:pass' })` (string); `{ auth: { username: 'x' } }` (password missing); `{ auth: null }`; `{ auth: ['u','p'] }` (array is not a record).

Common situations: Migrating from a config that stores credentials as a single string; env-var parsing that drops undefined keys; spreading a partial credentials object.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/729719249f24415f.json. Report an issue: GitHub.