mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Password must be a string

Error message

Password must be a string

What it means

Thrown by passwordDigest() (scram.ts:223) as a MongoInvalidArgumentError when the password is not a string. SCRAM-SHA-1 hashes the password as part of the digest; a non-string password (Buffer, number, undefined) cannot be processed. Defensive check inside the internal digest helper.

Source

Thrown at src/cmap/auth/scram.ts:223

function parsePayload(payload: Binary) {
  const payloadStr = ByteUtils.toUTF8(payload.buffer, 0, payload.position, false);
  const dict: Document = {};
  const parts = payloadStr.split(',');
  for (let i = 0; i < parts.length; i++) {
    const valueParts = (parts[i].match(/^([^=]*)=(.*)$/) ?? []).slice(1);
    dict[valueParts[0]] = valueParts[1];
  }
  return dict;
}

function passwordDigest(username: string, password: string) {
  if (typeof username !== 'string') {
    throw new MongoInvalidArgumentError('Username must be a string');
  }

  if (typeof password !== 'string') {
    throw new MongoInvalidArgumentError('Password must be a string');
  }

  if (password.length === 0) {
    throw new MongoInvalidArgumentError('Password cannot be empty');
  }

  let nodeCrypto;
  try {
    // TODO: NODE-7424 - remove dependency on 'crypto' for SCRAM-SHA-1 authentication
    // eslint-disable-next-line @typescript-eslint/no-require-imports
    nodeCrypto = require('crypto');
  } catch (e) {
    throw new MongoRuntimeError(
      'Node.js crypto module is required for SCRAM-SHA-1 authentication',
      {
        cause: e
      }
    );

View on GitHub (pinned to 3366c21a63)

Solutions

1. Coerce the password to a string before building credentials
2. If your secret store returns a Buffer, call .toString('utf8') first
3. Construct credentials through the standard MongoCredentials path so validation runs

Example fix

// before
const password = secretBuffer; // Buffer
// after
const password = secretBuffer.toString('utf8');

function assertStringPassword(p: unknown): asserts p is string {
  if (typeof p !== 'string') throw new TypeError('password must be a string');
}
const password = secretBuffer?.toString('utf8');
assertStringPassword(password);

function isStringPassword(p: unknown): p is string {
  return typeof p === 'string';
}

When it happens

Trigger: Credentials constructed with a non-string password - e.g. a Buffer, number, or undefined leaking through a credentials resolver that bypassed MongoCredentials validation.

Common situations: Password loaded from a secret manager that returned a Buffer; numeric-only password not stringified; a credentials object built without going through the standard constructor.

Related errors

• Username must be a string
• Password cannot be empty
• Username required for mechanism '${this.mechanism}'
• AuthContext must provide credentials.
• AuthContext must provide credentials.

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