mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Auth mechanism property ALLOWED_HOSTS must be an array of st

Error message

Auth mechanism property ALLOWED_HOSTS must be an array of strings.

What it means

Thrown for MONGODB-OIDC when authMechanismProperties.ALLOWED_HOSTS is provided but is not an array. ALLOWED_HOSTS restricts which MongoDB hostnames the driver will send the OIDC token to (preventing token theft via redirect); it must be an array of strings. This specific branch catches the non-array case (object, string, number, etc.).

Source

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

            ','
          )} 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)) {
      if (this.source != null && this.source !== '$external') {
        // TODO(NODE-3485): Replace this with a MongoAuthValidationError
        throw new MongoAPIError(
          `Invalid source '${this.source}' for mechanism '${this.mechanism}' specified.`
        );
      }
    }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Pass ALLOWED_HOSTS as an array: { ALLOWED_HOSTS: ['host.example.com'] }.
2. In a connection string, use the form authMechanismProperties=ALLOWED_HOSTS:host1,host2 (the parser splits on comma).
3. If building options programmatically, ensure the field is always an array.

Example fix

// before
authMechanismProperties: { ALLOWED_HOSTS: 'cluster.mongodb.net' }

// after
authMechanismProperties: { ALLOWED_HOSTS: ['cluster.mongodb.net'] }

function normalizeAllowedHosts(v: unknown): string[] {
  if (v == null) return [];
  if (!Array.isArray(v)) throw new Error('ALLOWED_HOSTS must be an array of strings');
  return v as string[];
}

function isStringArray(v: unknown): v is string[] {
  return Array.isArray(v) && v.every(x => typeof x === 'string');
}

When it happens

Trigger: In MongoCredentials.validate() when ALLOWED_HOSTS is truthy but Array.isArray(hosts) is false.

Common situations: Passing ALLOWED_HOSTS as a comma-separated string in the URI instead of an array (URI parsing usually splits these, but a programmatic options object may not); passing a single hostname string in the options object; misconfigured options spread.

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.
• Either a ENVIRONMENT, OIDC_CALLBACK, or OIDC_HUMAN_CALLBACK

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