mongodb/node-mongodb-native · critical · MongoMissingCredentialsError

AuthContext must provide credentials.

Error message

AuthContext must provide credentials.

What it means

Thrown by X509.prepare() (x509.ts:15) as a MongoMissingCredentialsError when the AuthContext has no credentials during the X.509 speculative authentication setup. X.509 auth presents a client certificate; without a credentials object the driver cannot build the authenticate command. Most often a connection-string/configuration problem.

Source

Thrown at src/cmap/auth/x509.ts:15

import type { Document } from '../../bson';
import { MongoMissingCredentialsError } from '../../error';
import { ns } from '../../utils';
import type { HandshakeDocument } from '../connect';
import { type AuthContext, AuthProvider } from './auth_provider';
import type { MongoCredentials } from './mongo_credentials';

export class X509 extends AuthProvider {
  override async prepare(
    handshakeDoc: HandshakeDocument,
    authContext: AuthContext
  ): Promise<HandshakeDocument> {
    const { credentials } = authContext;
    if (!credentials) {
      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
    }
    return { ...handshakeDoc, speculativeAuthenticate: x509AuthenticateCommand(credentials) };
  }

  override async auth(authContext: AuthContext) {
    const connection = authContext.connection;
    const credentials = authContext.credentials;
    if (!credentials) {
      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
    }
    const response = authContext.response;

    if (response?.speculativeAuthenticate) {
      return;
    }

    await connection.command(ns('$external.$cmd'), x509AuthenticateCommand(credentials), undefined);
  }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Provide a username (the certificate subject) in the connection string or auth option
2. Configure TLS client certificates: tlsCertificateKeyFile and tlsCAFile options
3. Ensure the authSource is $external for X.509
4. Verify the server has the client certificate's CA configured

Example fix

// before
const client = new MongoClient('mongodb://host/?authMechanism=MONGODB-X509');
// after
const client = new MongoClient('mongodb://CN=user@host/?authMechanism=MONGODB-X509&authSource=$external&tlsCertificateKeyFile=./client.pem&tlsCAFile=./ca.pem');

function hasX509Credentials(opts: { username?: string; tlsCertificateKeyFile?: string }): boolean {
  return Boolean(opts.username && opts.tlsCertificateKeyFile);
}
if (!hasX509Credentials(clientOptions)) throw new Error('X509 auth requires a username and tlsCertificateKeyFile');

interface X509Opts { username: string; tlsCertificateKeyFile: string; tlsCAFile: string; authSource: '$external'; }
function isX509Configured(o: any): o is X509Opts {
  return typeof o.username === 'string' && typeof o.tlsCertificateKeyFile === 'string';
}

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoMissingCredentialsError && /MONGODB-X509|credentials/i.test(e.message)) {
    // provide username + tlsCertificateKeyFile in client options
  }
  throw e;
}

When it happens

Trigger: Connecting with authMechanism=MONGODB-X509 but no username and no TLS client certificate configured; X509 selected via auto-negotiation without a credentials source; programmatic AuthContext construction without credentials.

Common situations: Forgetting to set tlsCertificateKeyFile when using X.509; mixing up MONGODB-X509 with MONGODB-AWS; connecting to a $external user store without configuring client certificates.

Related errors

• Password not allowed for mechanism MONGODB-X509
• Invalid source '${this.source}' for mechanism '${this.mechan
• Credentials required for GSSAPI authentication
• Username required for mechanism '${this.mechanism}'
• username and ENVIRONMENT '${this.mechanismProperties.ENVIRON

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