mongodb/node-mongodb-native · error · MongoAPIError

Password not allowed for mechanism MONGODB-X509

Error message

Password not allowed for mechanism MONGODB-X509

What it means

Thrown by MongoCredentials.validate() when MONGODB-X509 is used with a non-empty password. X509 authenticates via a client certificate distinguished name (the username), never a password; supplying one (other than an empty string, which is silently cleared) is treated as a configuration error.

Solutions

1. Remove the password entirely from the connection string/options.
2. Ensure TLS client certificates are configured via tlsCertificateKeyFile / sslContext, not password.
3. Leave username as the certificate subject (RFC2253 DN) if required by your server.

Example fix

// before
'mongodb://host/?authMechanism=MONGODB-X509&username=CN%3Dapp&password=secret'
// after
'mongodb://host/?authMechanism=MONGODB-X509&username=CN%3Dapp'

function assertX509NoPassword(mech, password) {
  if (mech === 'MONGODB-X509' && password != null && password !== '') {
    throw new Error('MONGODB-X509 does not allow a password.');
  }
}

When it happens

Trigger: Setting authMechanism='MONGODB-X509' along with a password in the connection string or credentials object. Fires at validate() line 270 (only when password is non-empty; empty-string password is auto-cleared).

Common situations: Reusing a username/password template and only changing the mechanism. Tooling that always populates password. Misunderstanding that X509 uses the certificate, not a secret.

Related errors

• AuthContext must provide credentials.
• AuthContext must provide credentials.
• 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/7d2184301eaa6cd3. Report an issue: GitHub.

Appendix: source

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

        // TODO(NODE-3485): Replace this with a MongoAuthValidationError
        throw new MongoAPIError(
          `Invalid source '${this.source}' for mechanism '${this.mechanism}' specified.`
        );
      }
    }

    if (this.mechanism === AuthMechanism.MONGODB_PLAIN && this.source == null) {
      // TODO(NODE-3485): Replace this with a MongoAuthValidationError
      throw new MongoAPIError('PLAIN Authentication Mechanism needs an auth source');
    }

    if (this.mechanism === AuthMechanism.MONGODB_X509 && this.password != null) {
      if (this.password === '') {
        Reflect.set(this, 'password', undefined);
        return;
      }
      // TODO(NODE-3485): Replace this with a MongoAuthValidationError
      throw new MongoAPIError(`Password not allowed for mechanism MONGODB-X509`);
    }

    const canonicalization = this.mechanismProperties.CANONICALIZE_HOST_NAME ?? false;
    if (!Object.values(GSSAPICanonicalizationValue).includes(canonicalization)) {
      throw new MongoAPIError(`Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}`);
    }
  }

  static merge(
    creds: MongoCredentials | undefined,
    options: Partial<MongoCredentialsOptions>
  ): MongoCredentials {
    return new MongoCredentials({
      username: options.username ?? creds?.username ?? '',
      password: options.password ?? creds?.password ?? '',
      mechanism: options.mechanism ?? creds?.mechanism ?? AuthMechanism.MONGODB_DEFAULT,
      mechanismProperties: options.mechanismProperties ?? creds?.mechanismProperties ?? {},
      source: options.source ?? options.db ?? creds?.source ?? 'admin'

View on GitHub (pinned to dce7939f86)