mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Either a ENVIRONMENT, OIDC_CALLBACK, or OIDC_HUMAN_CALLBACK…

Error message

Either a ENVIRONMENT, OIDC_CALLBACK, or OIDC_HUMAN_CALLBACK must be specified for mechanism '${this.mechanism}'.

What it means

Thrown by MongoCredentials.validate() when MONGODB-OIDC is selected but none of ENVIRONMENT, OIDC_CALLBACK, or OIDC_HUMAN_CALLBACK are provided. OIDC requires either a built-in machine environment or an explicit callback that returns the access token; with neither, authentication cannot proceed.

Solutions

1. Provide an ENVIRONMENT ('test'/'azure'/'gcp'/'k8s') for a built-in machine workflow.
2. Or supply OIDC_CALLBACK (machine/automated) or OIDC_HUMAN_CALLBACK (interactive) pointing at a function that returns an OIDCResponse.
3. Double-check the mechanismProperties object is actually passed through (URI uses authMechanismProperties=ENVIRONMENT:azure).

Example fix

// before
new MongoClient(url, { auth: { mechanism: 'MONGODB-OIDC' } });
// after
new MongoClient(url, { auth: { mechanism: 'MONGODB-OIDC', mechanismProperties: { OIDC_CALLBACK: tokenFetcher } } });

function assertOidcConfigured(props) {
  if (!props?.ENVIRONMENT && !props?.OIDC_CALLBACK && !props?.OIDC_HUMAN_CALLBACK) {
    throw new Error('MONGODB-OIDC requires ENVIRONMENT, OIDC_CALLBACK, or OIDC_HUMAN_CALLBACK.');
  }
}

When it happens

Trigger: Selecting authMechanism='MONGODB-OIDC' with empty or absent mechanismProperties. Triggered during validate() on the first connection/auth attempt.

Common situations: Setting the mechanism name but forgetting to supply mechanismProperties. Migrating from a different mechanism and dropping the properties object. Misunderstanding that OIDC needs a callback or environment by design.

Related errors

• Auth mechanism property ALLOWED_HOSTS must be an array of…
• AuthContext must provide credentials.
• Currently only a ENVIRONMENT in
• No password is allowed in ENVIRONMENT
• No workflow provided to the OIDC auth provider.

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

Appendix: source

Thrown at src/cmap/auth/mongo_credentials.ts:232

      }

      if (
        this.mechanismProperties.ENVIRONMENT &&
        !ALLOWED_ENVIRONMENT_NAMES.includes(this.mechanismProperties.ENVIRONMENT)
      ) {
        throw new MongoInvalidArgumentError(
          `Currently only a ENVIRONMENT in ${ALLOWED_ENVIRONMENT_NAMES.join(
            ','
          )} is supported for mechanism '${this.mechanism}'.`
        );
      }

      if (
        !this.mechanismProperties.ENVIRONMENT &&
        !this.mechanismProperties.OIDC_CALLBACK &&
        !this.mechanismProperties.OIDC_HUMAN_CALLBACK
      ) {
        throw new MongoInvalidArgumentError(
          `Either a ENVIRONMENT, OIDC_CALLBACK, or OIDC_HUMAN_CALLBACK must be specified for mechanism '${this.mechanism}'.`
        );
      }

      if (this.mechanismProperties.ALLOWED_HOSTS) {
        const hosts = this.mechanismProperties.ALLOWED_HOSTS;
        if (!Array.isArray(hosts)) {
          throw new MongoInvalidArgumentError(ALLOWED_HOSTS_ERROR);
        }
        for (const host of hosts) {
          if (typeof host !== 'string') {
            throw new MongoInvalidArgumentError(ALLOWED_HOSTS_ERROR);
          }
        }
      }
    }

    if (AUTH_MECHS_AUTH_SRC_EXTERNAL.has(this.mechanism)) {

View on GitHub (pinned to dce7939f86)