mongodb/node-mongodb-native · error · MongoMissingCredentialsError

AuthContext must provide credentials.

Error message

AuthContext must provide credentials.

What it means

Thrown at the start of the MONGODB-AWS auth provider's auth() method when the AuthContext carries no credentials. AWS authentication needs an access key id / secret access key (or a credential provider chain to fetch them); without any credentials the workflow cannot begin.

Solutions

  1. Provide static AWS credentials via username/password in the connection string, or via the AWS_* environment variables.
  2. Run the client on an EC2/ECS/EKS instance with an IAM role so the SDK credential provider chain can fetch temporary credentials.
  3. If using authMechanism=MONGODB-AWS explicitly, ensure at least one credential source is available before connect().

Example fix

// before
new MongoClient('mongodb://host/?authMechanism=MONGODB-AWS');
// after
new MongoClient('mongodb://AKIA...:secret@host/?authMechanism=MONGODB-AWS');
Defensive patterns

Strategy: validation

Validate before calling

function assertAwsCredentialsPresent(opts, env=process.env) {
  const hasStatic = opts.auth?.username || env.AWS_ACCESS_KEY_ID;
  const hasRole = env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI || env.AWS_WEB_IDENTITY_TOKEN_FILE || env.AWS_ROLE_SESSION_NAME;
  if (opts.auth?.mechanism === 'MONGODB-AWS' && !hasStatic && !hasRole) {
    throw new Error('MONGODB-AWS needs static keys, IAM role, or AWS env vars.');
  }
}

Try / catch

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoMissingCredentialsError && /AWS/.test(String(e.message))) {
    // surface guidance to attach an IAM role or set AWS env vars
  }
  throw e;
}

Prevention

When it happens

Trigger: The driver selected MONGODB-AWS as the auth mechanism but no username/password and no AWS credential provider resolved to credentials. Fires at mongodb_aws.ts:41 inside MongoDBAWS.auth().

Common situations: Specifying authMechanism=MONGODB-AWS while neither setting AWS env vars (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY) nor providing credentials, and not running in an IAM-role environment. Forgetting to pass the username/password for static AWS keys.

Related errors

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

Appendix: source

Thrown at src/cmap/auth/mongodb_aws.ts:41

interface AWSSaslContinuePayload {
  a: string;
  d: string;
  t?: string;
}

export class MongoDBAWS extends AuthProvider {
  private credentialFetcher: AWSSDKCredentialProvider;

  constructor(credentialProvider?: AWSCredentialProvider) {
    super();
    this.credentialFetcher = new AWSSDKCredentialProvider(credentialProvider);
  }

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

    authContext.credentials = await makeTempCredentials(
      authContext.credentials,
      this.credentialFetcher
    );

    const { credentials } = authContext;

    const accessKeyId = credentials.username;
    const secretAccessKey = credentials.password;
    // Allow the user to specify an AWS session token for authentication with temporary credentials.
    const sessionToken = credentials.mechanismProperties.AWS_SESSION_TOKEN;

    // If all three defined, include sessionToken, else only include username and pass
    const awsCredentials = sessionToken
      ? { accessKeyId, secretAccessKey, sessionToken }
      : { accessKeyId, secretAccessKey };

View on GitHub (pinned to dce7939f86)