mongodb/node-mongodb-native · critical · MongoMissingCredentialsError

AuthContext must provide credentials.

Error message

AuthContext must provide credentials.

What it means

Thrown by getCredentials in the OIDC auth provider (mongodb_oidc.ts:182) when the AuthContext has no credentials object at all. OIDC still requires a MongoCredentials to carry mechanismProperties (ENVIRONMENT, TOKEN_RESOURCE) and optional username; if connection parsing produced no credentials, the OIDC provider cannot run. Raised as MongoMissingCredentialsError.

Solutions

1. Provide the OIDC mechanismProperties so credentials parse: authMechanismProperties=ENVIRONMENT:<env>,TOKEN_RESOURCE:<audience>
2. If using the callback flow, ensure oidc callback / mechanismProperties are set on the MongoClient options
3. Verify the connection string is well-formed and the auth section is not stripped

Example fix

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

// after
const client = new MongoClient(
  'mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<audience>'
);

const mech = clientOptions.auth?.mechanism;
const hasCreds =
  clientOptions.auth?.username !== undefined ||
  /:[^:@]*@/.test(uri); // crude user:pass in URI
if (mech === 'MONGODB-OIDC' && !clientOptions.auth?.mechananismProperties && !hasCreds) {
  throw new Error('OIDC selected but no mechanismProperties/credentials provided');
}

try {
  await client.connect();
} catch (err) {
  if (err instanceof MongoMissingCredentialsError) {
    // rebuild the URI with authMechanismProperties and retry once
  } else throw err;
}

When it happens

Trigger: Selecting MONGODB-OIDC auth but the connection/options did not yield a MongoCredentials object (e.g., authMechanism set without the supporting mechanismProperties, or a programmatic MongoClient with no credentials option).

Common situations: Setting authMechanism=MONGODB-OIDC on a connection string with no username and no mechanismProperties. Building MongoClient programmatically and passing auth: { mechanism: 'MONGODB-OIDC' } without mechanismProperties. A mismatch between the auth source and the mechanism leaving credentials null.

Related errors

• No password is allowed in ENVIRONMENT
• Auth mechanism property ALLOWED_HOSTS must be an array of…
• AuthContext must provide credentials.
• AuthContext must provide credentials.
• AuthContext must provide credentials.

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

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