mongodb/node-mongodb-native · error · MongoMissingCredentialsError

Username required for mechanism

Error message

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

What it means

Thrown by MongoCredentials.validate for the SCRAM (SHA-1/SHA-256), GSSAPI, and PLAIN mechanisms when no username is set. These mechanisms all authenticate a named principal; an empty username makes authentication impossible. It is a MongoMissingCredentialsError raised when credentials are first validated.

Solutions

1. Provide a username in the connection string: mongodb://user:password@host/db?authSource=admin.
2. If using X.509 (no username needed), set authMechanism=MONGODB-X509 explicitly.
3. If building credentials in code, pass { username, password } to the auth options.

Example fix

// before
new MongoClient('mongodb://host/db?authSource=admin');
// after
new MongoClient('mongodb://user:pass@host/db?authSource=admin');

function assertUsernameForMechanism(uri, mechanism) {
  const scramLike = /^(SCRAM-SHA-1|SCRAM-SHA-256|GSSAPI|PLAIN)$/i.test(mechanism);
  const u = new URL(uri);
  if (scramLike && !u.username) {
    throw new Error(`Username required for mechanism ${mechanism}`);
  }
}

When it happens

Trigger: Connecting with authMechanism=SCRAM-SHA-256 (default when a username is expected) or explicitly GSSAPI/PLAIN/SCRAM-SHA-1, but the URI/connection options have no username; credentials object built without username; username set to empty string.

Common situations: URI mongodb://host/db?authSource=admin with no user@ prefix; providing only a password; copying a connection string and dropping the user portion; MONGODB-X509 intended but authMechanism left as default SCRAM.

Related errors

• AuthContext must provide credentials.
• Password cannot be empty
• AuthContext must provide credentials.
• AuthContext must provide credentials.
• AuthContext must provide credentials.

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

Appendix: 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 dce7939f86)