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 for MONGODB-OIDC when none of ENVIRONMENT, OIDC_CALLBACK, or OIDC_HUMAN_CALLBACK is configured. OIDC needs at least one source of tokens: a managed-identity ENVIRONMENT (machine) or a callback (machine or human interactive). Without any, the driver has no way to obtain an access token.

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 3366c21a63)

Solutions

1. Add ENVIRONMENT (test/azure/gcp/k8s) for machine workflows.
2. Provide OIDC_CALLBACK (machine) or OIDC_HUMAN_CALLBACK (interactive browser/device-code) function for custom IdPs.
3. Double-check the authMechanismProperties string parses correctly in the URI.

Example fix

// before
'mongodb://host/?authMechanism=MONGODB-OIDC'

// after (interactive callback)
const client = new MongoClient(uri, {
  authMechanism: 'MONGODB-OIDC',
  authMechanismProperties: { OIDC_HUMAN_CALLBACK: myBrowserCallback }
});

function validateOidcSource(props?: { ENVIRONMENT?: string; OIDC_CALLBACK?: unknown; OIDC_HUMAN_CALLBACK?: unknown }) {
  if (!props?.ENVIRONMENT && !props?.OIDC_CALLBACK && !props?.OIDC_HUMAN_CALLBACK) {
    throw new Error('OIDC requires ENVIRONMENT or a callback');
  }
}

import { MongoInvalidArgumentError } from 'mongodb';
function isOidcNoSource(e: unknown): boolean {
  return e instanceof MongoInvalidArgumentError && /Either a ENVIRONMENT, OIDC_CALLBACK, or OIDC_HUMAN_CALLBACK/.test(e.message);
}

When it happens

Trigger: In MongoCredentials.validate() OIDC branch when all three of ENVIRONMENT, OIDC_CALLBACK, OIDC_HUMAN_CALLBACK are unset.

Common situations: Setting authMechanism=MONGODB-OIDC with no mechanism properties; migrating from a test setup that relied on ENVIRONMENT:test and forgetting to port the property; assuming OIDC defaults to some provider.

Related errors

• username and ENVIRONMENT '${this.mechanismProperties.ENVIRON
• No password is allowed in ENVIRONMENT '${this.mechanismPrope
• TOKEN_RESOURCE must be set in the auth mechanism properties
• Currently only a ENVIRONMENT in ${ALLOWED_ENVIRONMENT_NAMES.
• Auth mechanism property ALLOWED_HOSTS must be an array of st

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