mongodb/node-mongodb-native · error · MongoMissingCredentialsError

Username required for mechanism '${this.mechanism}'

Error message

Username required for mechanism '${this.mechanism}'

What it means

Thrown by MongoCredentials.validate() when the auth mechanism is one of GSSAPI, PLAIN, SCRAM-SHA-1, or SCRAM-SHA-256 but no username was provided. These mechanisms all require a username to perform authentication. X509 and AWS and OIDC have their own rules and are handled separately.

Source

Thrown at src/cmap/auth/mongo_credentials.ts:188

        password: this.password,
        source: this.source,
        mechanism: getDefaultAuthMechanism(hello),
        mechanismProperties: this.mechanismProperties
      });
    }

    return this;
  }

  validate(): void {
    if (
      (this.mechanism === AuthMechanism.MONGODB_GSSAPI ||
        this.mechanism === AuthMechanism.MONGODB_PLAIN ||
        this.mechanism === AuthMechanism.MONGODB_SCRAM_SHA1 ||
        this.mechanism === AuthMechanism.MONGODB_SCRAM_SHA256) &&
      !this.username
    ) {
      throw new MongoMissingCredentialsError(`Username required for mechanism '${this.mechanism}'`);
    }

    if (this.mechanism === AuthMechanism.MONGODB_OIDC) {
      if (
        this.username &&
        this.mechanismProperties.ENVIRONMENT &&
        this.mechanismProperties.ENVIRONMENT !== 'azure'
      ) {
        throw new MongoInvalidArgumentError(
          `username and ENVIRONMENT '${this.mechanismProperties.ENVIRONMENT}' may not be used together for mechanism '${this.mechanism}'.`
        );
      }

      if (this.username && this.password) {
        throw new MongoInvalidArgumentError(
          `No password is allowed in ENVIRONMENT '${this.mechanismProperties.ENVIRONMENT}' for '${this.mechanism}'.`
        );
      }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Add the username to the connection string: 'mongodb://username:password@host/?authSource=...'.
2. Pass { auth: { username, password } } in MongoClient options.
3. Confirm the username wasn't stripped by URL parsing (encode special chars).

Example fix

// before
new MongoClient('mongodb://host/?authSource=admin');

// after
new MongoClient('mongodb://alice:secret@host/?authSource=admin');

function validateCredentials(opts: { username?: string; mechanism?: string }) {
  const mechs = ['GSSAPI','PLAIN','SCRAM-SHA-1','SCRAM-SHA-256'];
  if (opts.mechanism && mechs.includes(opts.mechanism) && !opts.username) {
    throw new Error(`Username required for mechanism ${opts.mechanism}`);
  }
}

import { MongoMissingCredentialsError } from 'mongodb';
function isUsernameRequired(e: unknown): boolean {
  return e instanceof MongoMissingCredentialsError && /Username required for mechanism/.test(e.message);
}

When it happens

Trigger: In MongoCredentials.validate() during connection setup when mechanism is in the SCRAM/GSSAPI/PLAIN set and username is empty.

Common situations: Connection string missing the username component; credentials object created without username; SCRAM auth attempted with only a password; copy/paste connection string that dropped the user@ prefix.

Related errors

• Credentials required for GSSAPI authentication
• Invalid source '${this.source}' for mechanism '${this.mechan
• PLAIN Authentication Mechanism needs an auth source
• 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/726bab1b10e01a17.json. Report an issue: GitHub.