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 for MONGODB-X509 when a non-empty password is provided. X509 authenticates via a client certificate presented during TLS, so a password is meaningless and rejected. (An empty-string password is silently coerced to undefined and allowed, to tolerate connection-string builders that inject an empty password.)

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

Solutions

1. Remove the password from the connection string for X509 auth.
2. If the password is empty in code, that's tolerated; otherwise delete it.
3. Ensure the client certificate is supplied via tlsCertificateKeyFile (or tlsFile / X509 env).

Example fix

// before
'mongodb://CN=app@host/?authMechanism=MONGODB-X509&authSource=$external&password=secret'

// after
'mongodb://CN=app@host/?authMechanism=MONGODB-X509&authSource=$external'

function validateX509(mechanism: string, password?: string) {
  if (mechanism === 'MONGODB-X509' && password && password !== '') {
    throw new Error('Password not allowed for MONGODB-X509');
  }
}

import { MongoAPIError } from 'mongodb';
function isX509PasswordForbidden(e: unknown): boolean {
  return e instanceof MongoAPIError && /Password not allowed for mechanism MONGODB-X509/.test(e.message);
}

When it happens

Trigger: In MongoCredentials.validate() when mechanism === MONGODB_X509 and password != null and password !== ''.

Common situations: Reusing a SCRAM-style username:password connection string and switching to MONGODB-X509; tooling that auto-populates a placeholder password; URL with a stray ':password' before the '@'.

Related errors

• Invalid source '${this.source}' for mechanism '${this.mechan
• AuthContext must provide credentials.
• username and ENVIRONMENT '${this.mechanismProperties.ENVIRON
• No password is allowed in ENVIRONMENT '${this.mechanismPrope
• PLAIN Authentication Mechanism needs an auth source

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