mongodb/node-mongodb-native · error · MongoAPIError

AWS_SESSION_TOKEN cannot be provided when using…

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 by MongoAPIError when authMechanism=MONGODB-AWS and `AWS_SESSION_TOKEN` is set inside `authMechanismProperties` (URI or options). The session token must come through the AWS SDK's own discovery chain, not through driver options. Located at src/connection_string.ts:429, immediately after the username/password check in the isAws branch.

Solutions

1. Remove AWS_SESSION_TOKEN from authMechanismProperties and set the AWS_SESSION_TOKEN environment variable instead.
2. Supply all three temporary credentials (access key id, secret, session token) via AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN env vars; the AWS SDK will pick them up.
3. If running on EC2/ECS/EKS, drop static token passing entirely and attach an IAM role to the compute.

Example fix

// before
new MongoClient('mongodb+srv://host/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:FwoGZX...')

// after
process.env.AWS_SESSION_TOKEN = 'FwoGZX...'
new MongoClient('mongodb+srv://host/?authMechanism=MONGODB-AWS')

function assertAwsNoSessionToken(options = {}, uri = '') {
  const amp = options.authMechanismProperties?.AWS_SESSION_TOKEN || (uri.match(/AWS_SESSION_TOKEN:([^&]+)/)?.[1]);
  const isAws = /aws/i.test(options.authMechanism || '') || /authMechanism=MONGODB-AWS/i.test(uri);
  if (isAws && amp) throw new Error('Pass AWS_SESSION_TOKEN via env var, not authMechanismProperties.');
}

try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoAPIError && /AWS_SESSION_TOKEN/.test(e.message)) { delete options.authMechanismProperties?.AWS_SESSION_TOKEN; process.env.AWS_SESSION_TOKEN = token; } else throw e; }

When it happens

Trigger: URI `...?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:FwoG...` or options `{ authMechanism: 'MONGODB-AWS', authMechanismProperties: { AWS_SESSION_TOKEN: '...' } }`.

Common situations: Using STS temporary credentials and trying to pass the session token via authMechanismProperties; copy-pasting an example that worked for a different driver language; assuming the token is read like other mechanism props.

Related errors

• username and password cannot be provided when using…
• AuthContext must provide credentials.
• authMechanism not supported
• authMechanism one of
• AuthMechanismProperties must be an object

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

Appendix: 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 dce7939f86)