mongodb/node-mongodb-native · error · MongoAPIError

AWS_SESSION_TOKEN cannot be provided when using MONGODB-AWS.

Error message

AWS_SESSION_TOKEN cannot be provided when using MONGODB-AWS. Credentials must be provided in a manner that can be read by the AWS SDK.

What it means

Thrown (as MongoAPIError) when MONGODB-AWS is used and the credentials carry an AWS_SESSION_TOKEN property (connection_string.ts:428-432). Session tokens must come from the AWS SDK credential chain (typically the AWS_SESSION_TOKEN env var) so they pair correctly with temporary access keys; passing them via authMechanismProperties is rejected.

Source

Thrown at src/connection_string.ts:429

      mongoOptions.dbName &&
      !allProvidedOptions.has('authSource')
    ) {
      // inherit the dbName unless GSSAPI or X509, then silently ignore dbName
      // and there was no specific authSource given
      mongoOptions.credentials = MongoCredentials.merge(mongoOptions.credentials, {
        source: mongoOptions.dbName
      });
    }

    if (isAws) {
      const { username, password } = mongoOptions.credentials;
      if (username || password) {
        throw new MongoAPIError(
          'username and password cannot be provided when using MONGODB-AWS. Credentials must be provided in a manner that can be read by the AWS SDK.'
        );
      }
      if (mongoOptions.credentials.mechanismProperties.AWS_SESSION_TOKEN) {
        throw new MongoAPIError(
          'AWS_SESSION_TOKEN cannot be provided when using MONGODB-AWS. Credentials must be provided in a manner that can be read by the AWS SDK.'
        );
      }
    }

    mongoOptions.credentials.validate();

    // Check if the only auth related option provided was authSource, if so we can remove credentials
    if (
      mongoOptions.credentials.password === '' &&
      mongoOptions.credentials.username === '' &&
      mongoOptions.credentials.mechanism === AuthMechanism.MONGODB_DEFAULT &&
      Object.keys(mongoOptions.credentials.mechanismProperties).length === 0
    ) {
      delete mongoOptions.credentials;
    }
  }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Remove AWS_SESSION_TOKEN from authMechanismProperties and the connection string.
2. Export AWS_SESSION_TOKEN (along with AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY) as an environment variable.
3. Prefer an instance/role-based credential source so tokens rotate automatically.

Example fix

// before
const c = new MongoClient(uri, {
  authMechanism: 'MONGODB-AWS',
  authMechanismProperties: { AWS_SESSION_TOKEN: process.env.AWS_SESSION_TOKEN }
});
// after
const c = new MongoClient(uri, { authMechanism: 'MONGODB-AWS' });
// AWS_SESSION_TOKEN is read from env by the AWS SDK automatically

const mech = opts.authMechanism ?? new URL(uri).searchParams.get('authMechanism');
if (mech === 'MONGODB-AWS' && opts.authMechanismProperties?.AWS_SESSION_TOKEN) {
  throw new Error('Pass AWS_SESSION_TOKEN via the environment, not authMechanismProperties');
}

When it happens

Trigger: Options like { authMechanism: 'MONGODB-AWS', authMechanismProperties: { AWS_SESSION_TOKEN: '...' } } or a URI embedding session-token via authMechanismProperties.

Common situations: Using STS temporary credentials and trying to thread the session token through the URI instead of env vars; copying an AWS SDK sample's credentials object into MongoDB options.

Related errors

• username and password cannot be provided when using MONGODB-
• AuthContext must provide credentials.
• Server nonce does not begin with client nonce
• Server returned an invalid host: "${host}"
• Could not obtain temporary MONGODB-AWS credentials

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