mongodb/node-mongodb-native · error · MongoParseError

AuthMechanismProperties must be an object

Error message

AuthMechanismProperties must be an object

What it means

`authMechanismProperties` accepts either a connection-string-style string (e.g. 'SERVICE_NAME:svc,CANONICALIZE_HOST_NAME:true') or a plain object. The transform (src/connection_string.ts:702-729) iterates values; any value that is neither a string nor a plain object (record) triggers this MongoParseError.

Source

Thrown at src/connection_string.ts:721

    target: 'credentials',
    transform({ options, values }): MongoCredentials {
      // We can have a combination of options passed in the URI and options passed
      // as an object to the MongoClient. So we must transform the string options
      // as well as merge them together with a potentially provided object.
      let mechanismProperties = Object.create(null);

      for (const optionValue of values) {
        if (typeof optionValue === 'string') {
          for (const [key, value] of entriesFromString(optionValue)) {
            try {
              mechanismProperties[key] = getBoolean(key, value);
            } catch {
              mechanismProperties[key] = value;
            }
          }
        } else {
          if (!isRecord(optionValue)) {
            throw new MongoParseError('AuthMechanismProperties must be an object');
          }
          mechanismProperties = { ...optionValue };
        }
      }
      return MongoCredentials.merge(options.credentials, {
        mechanismProperties
      });
    }
  },
  authSource: {
    target: 'credentials',
    transform({ options, values: [value] }): MongoCredentials {
      const source = String(value);
      return MongoCredentials.merge(options.credentials, { source });
    }
  },
  autoEncryption: {
    type: 'record'

View on GitHub (pinned to 3366c21a63)

Solutions

1. Pass authMechanismProperties as an object: { SERVICE_NAME: 'kerberos', CANONICALIZE_HOST_NAME: true }
2. Or as a comma-delimited string: 'SERVICE_NAME:kerberos,CANONICALIZE_HOST_NAME:true'
3. For OIDC TOKEN_RESOURCE values containing commas, pass as an object (cannot be expressed in the URI)

Example fix

// before
new MongoClient(uri, { authMechanismProperties: 123 });
// after
new MongoClient(uri, {
  authMechanismProperties: { SERVICE_NAME: 'mongod', CANONICALIZE_HOST_NAME: true }
});

function isValidMechProperties(v) {
  return typeof v === 'string' || (v != null && typeof v === 'object' && !Array.isArray(v));
}
if (options.authMechanismProperties && !isValidMechProperties(options.authMechanismProperties)) {
  throw new TypeError('authMechanismProperties must be a string or object');
}

function isAuthMechanismProperties(v) {
  return typeof v === 'string' || (v != null && typeof v === 'object' && !Array.isArray(v));
}

When it happens

Trigger: `{ authMechanismProperties: 123 }`; `{ authMechanismProperties: true }`; `{ authMechanismProperties: ['SERVICE_NAME:x'] }` (array is not an object); `{ authMechanismProperties: null }`.

Common situations: Loosely-typed config producing a number/boolean; JSON config parsed to an unexpected type; passing an array instead of an object.

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/81122c04512beb96.json. Report an issue: GitHub.