mongodb/node-mongodb-native · error · MongoParseError

AuthMechanismProperties must be an object

Error message

AuthMechanismProperties must be an object

What it means

Thrown by MongoParseError at src/connection_string.ts:721 in the `authMechanismProperties` transform. When a value is supplied as an object (not a URI string), it must be a plain record; anything else (array, string-coerced primitive, null) is rejected. String values are parsed as key:value pairs and are not subject to this check.

Solutions

1. Pass `authMechanismProperties` as a plain object, e.g. `{ ALLOWED_HOSTS: ['example.com'] }` for OIDC.
2. If passing via the URI, use the string form `?authMechanismProperties=K:V,K2:V2` (the driver parses it).
3. Validate the value is a non-null object before assigning it.

Example fix

// before
new MongoClient(uri, { authMechanism: 'MONGODB-OIDC', authMechanismProperties: 'ALLOWED_HOSTS:example.com' })

// after (object form when not in URI)
new MongoClient(uri, { authMechanism: 'MONGODB-OIDC', authMechanismProperties: { ALLOWED_HOSTS: ['example.com'] } })

function isPlainObject(v) { return typeof v === 'object' && v !== null && !Array.isArray(v); }
function assertMechPropsObject(options) { const p = options.authMechanismProperties; if (p != null && typeof p !== 'string' && !isPlainObject(p)) throw new Error('authMechanismProperties must be a string or plain object.'); }

function isMechProps(v): v is Record<string, unknown> { return typeof v === 'object' && v !== null && !Array.isArray(v); }

try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoParseError && /AuthMechanismProperties must be an object/.test(e.message)) { options.authMechanismProperties = typeof options.authMechanismProperties === 'string' ? options.authMechanismProperties : {}; } else throw e; }

When it happens

Trigger: `{ authMechanismProperties: ['AWS_SESSION_TOKEN:x'] }`, `{ authMechanismProperties: 42 }`, or `null` passed where an object was expected.

Common situations: Passing mechanism properties as an array because the URI form looks comma-like; loading the value from a config file as the wrong YAML/JSON type.

Related errors

• must be an object with 'username' and 'password' properties
• authMechanism one of
• must be an object
• authMechanism not supported
• AWS_SESSION_TOKEN cannot be provided when using…

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

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