mongodb/node-mongodb-native · error · MongoMissingCredentialsError

AuthContext must provide credentials.

Error message

AuthContext must provide credentials.

What it means

Thrown by the OIDC auth provider's getCredentials() helper when the AuthContext has no credentials object (src/cmap/auth/mongodb_oidc.ts:181). MONGODB-OIDC requires at least the mechanism (and for some environments a username or ENVIRONMENT/TOKEN_RESOURCE) to be configured. Surfaced as a MongoMissingCredentialsError.

Source

Thrown at src/cmap/auth/mongodb_oidc.ts:182

   */
  override async prepare(
    handshakeDoc: HandshakeDocument,
    authContext: AuthContext
  ): Promise<HandshakeDocument> {
    const { connection } = authContext;
    const credentials = getCredentials(authContext);
    const result = await this.workflow.speculativeAuth(connection, credentials);
    return { ...handshakeDoc, ...result };
  }
}

/**
 * Get credentials from the auth context, throwing if they do not exist.
 */
function getCredentials(authContext: AuthContext): MongoCredentials {
  const { credentials } = authContext;
  if (!credentials) {
    throw new MongoMissingCredentialsError(MISSING_CREDENTIALS_ERROR);
  }
  return credentials;
}

View on GitHub (pinned to 3366c21a63)

Solutions

1. Provide authMechanismProperties including ENVIRONMENT (e.g. ENVIRONMENT:azure,TOKEN_RESOURCE:...) or a valid OIDC callback.
2. For username/password-style OIDC (multi-tenant), set the username as appropriate for your IdP.
3. Verify the connection string includes authMechanism=MONGODB-OIDC and that authSource is $external.
4. Confirm you are on a driver version that supports MONGODB-OIDC.

Example fix

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

// after
const c = new MongoClient(
  'mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:https://cluster.example.com'
);

function validateOidcCredentials(uri: string): void {
  if (!/authMechanism=MONGODB-OIDC/i.test(uri)) return;
  const hasEnvOrCallback = /ENVIRONMENT=/i.test(uri) || /OIDC_CALLBACK=/i.test(uri);
  if (!hasEnvOrCallback) {
    throw new Error('MONGODB-OIDC requires ENVIRONMENT or a callback in authMechanismProperties');
  }
}
validateOidcCredentials(connectionString);

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoMissingCredentialsError && /AuthContext must provide credentials/.test(e.message) && mechanism === 'MONGODB-OIDC') {
    throw new Error('OIDC auth needs ENVIRONMENT (and TOKEN_RESOURCE) or a callback configured.');
  }
  throw e;
}

When it happens

Trigger: Connecting with authMechanism=MONGODB-OIDC but without any credentials materializing in the AuthContext - e.g. omitting the mechanism properties entirely, or a credential merge step that produced no credentials object. Also triggered when ENVIRONMENT is not one of the recognized values so no workflow is selected and credentials end up empty.

Common situations: Specifying authMechanism=MONGODB-OIDC with no authMechanismProperties at all, misspelling ENVIRONMENT (e.g. ENV:azure), or expecting callback-based OIDC without registering the callback.

Related errors

• username and ENVIRONMENT '${this.mechanismProperties.ENVIRON
• No password is allowed in ENVIRONMENT '${this.mechanismPrope
• Invalid source '${this.source}' for mechanism '${this.mechan
• TOKEN_RESOURCE must be set in the auth mechanism properties
• User provided OIDC callbacks must return a valid object with

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