What causes "AuthContext must provide credentials." in mongodb/node-mongodb-native?

Provide AWS credentials in the connection string: username= &password= with authMechanism=MONGODB-AWS.

mongodb/node-mongodb-native · error · MongoMissingCredentialsError

AuthContext must provide credentials.

Error message

AuthContext must provide credentials.

What it means

Thrown by the MONGODB-AWS auth provider when the AuthContext has no credentials object at the start of authentication (src/cmap/auth/mongodb_aws.ts:40). MONGODB-AWS requires either static AWS credentials (access key id as username, secret access key as password) or a resolved set of temporary credentials; with none present the provider cannot proceed. Surfaced as a MongoMissingCredentialsError.

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

Solutions

Provide AWS credentials in the connection string: username=<accessKeyId>&password=<secretAccessKey> with authMechanism=MONGODB-AWS.
Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (and AWS_SESSION_TOKEN if using temporary creds) in the environment.
Attach an IAM role to the compute (EC2 instance profile, ECS task role, EKS pod identity) so the AWS SDK credential provider chain can resolve credentials automatically.
Ensure the 'mongodb' (AWS SDK v3) optional dependency is installed if relying on the provider chain.

Example fix

// before
const client = new MongoClient('mongodb://host/?authMechanism=MONGODB-AWS');

// after (static creds)
const client = new MongoClient(
  'mongodb://AKIA...:secret@host/?authMechanism=MONGODB-AWS&authSource=%24external'
);
// or rely on env/instance role and just specify the mechanism

Defensive patterns

Strategy: validation

Validate before calling

function hasAwsCredentials(): boolean {
  return Boolean(
    (process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY) ||
    // or static creds in the URI; check your connection string parse result
    Boolean(uriUsername && uriPassword)
  );
}
if (mechanism === 'MONGODB-AWS' && !hasAwsCredentials()) {
  throw new Error('MONGODB-AWS requires AWS credentials (env vars, instance role, or URI username/password).');
}

Try / catch

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoMissingCredentialsError && /MONGODB-AWS|AuthContext/.test(e.message)) {
    // surface a friendlier message guiding to AWS credential setup
    throw new Error('No AWS credentials found. Set AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or attach an IAM role.');
  }
  throw e;
}

Prevention

Run 'aws sts get-caller-identity' in the same environment as the app to confirm the AWS SDK can find credentials.
In CI, inject AWS creds via secure environment variables or an instance role.
Validate that the optional 'mongodb' (AWS SDK) dependency is installed if you rely on the provider chain.

When it happens

Trigger: Connecting with authMechanism=MONGODB-AWS but omitting both username/password and any AWS credential source, or when the credential merge step produces an empty credentials object. Also triggered when the AWS SDK credential provider chain fails to find any credentials and the fallback path yields nothing.

Common situations: Running locally without AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY env vars set, no attached IAM role on EC2/ECS/EKS, no shared credentials file (~/.aws/credentials), and no credentials passed in the URI. Misconfigured CI environment that lacks AWS permissions.

Related errors

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