mongodb/node-mongodb-native · error · MongoParseError

must be an object

Error message

${name} must be an object

What it means

Thrown by MongoParseError at src/connection_string.ts:617 inside `setOption`'s `record` case when the supplied value fails `isRecord()`. Any option typed as `record` (e.g. `autoEncryption`) must be a plain object; passing a string, number, array, or null is rejected. `${name}` is the resolved option name.

Solutions

1. Pass the option as a plain object literal matching the expected schema (e.g. AutoEncryptionOptions).
2. If the value comes from JSON, parse it before passing it: `JSON.parse(value)`.
3. Check the option name in the error message (`${name}`) to identify which field is malformed.

Example fix

// before
new MongoClient(uri, { autoEncryption: '{ keyVaultNamespace: "encryption.__keyVault" }' })

// after
new MongoClient(uri, { autoEncryption: { keyVaultNamespace: 'encryption.__keyVault', kmsProviders: { aws: {} } } })

function isPlainObject(v) { return typeof v === 'object' && v !== null && !Array.isArray(v); }
function assertRecordOptions(options) {
  for (const [k, v] of Object.entries(options)) if (!isPlainObject(v) && /autoEncryption|readConcern|writeConcern/.test(k)) throw new Error(`${k} must be an object.`);
}

function isRecord(v, requiredKeys = []) { if (typeof v !== 'object' || v === null || Array.isArray(v)) return false; return requiredKeys.every(k => k in v); }

try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoParseError && /must be an object$/.test(e.message)) { /* coerce or remove the offending option */ } else throw e; }

When it happens

Trigger: Passing `autoEncryption: 'required'` instead of an object; passing `autoEncryption: null`; double-encoding JSON (passing a stringified object).

Common situations: Loading options from a JSON or YAML file and accidentally leaving the value as a string; toggling a feature flag where the type changed between driver versions.

Related errors

• authMechanism one of
• AuthMechanismProperties must be an object
• Invalid server API version=
• Invalid `serverApi` property; must specify a version from…
• must be an object with 'username' and 'password' properties

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

Appendix: source

Thrown at src/connection_string.ts:617

      break;
    case 'int':
      mongoOptions[name] = getIntFromOptions(name, values[0]);
      break;
    case 'uint':
      mongoOptions[name] = getUIntFromOptions(name, values[0]);
      break;
    case 'string':
      if (values[0] == null) {
        break;
      }
      // The value should always be a string here, but since the array is typed as unknown
      // there still needs to be an explicit cast.
      // eslint-disable-next-line @typescript-eslint/no-base-to-string
      mongoOptions[name] = String(values[0]);
      break;
    case 'record':
      if (!isRecord(values[0])) {
        throw new MongoParseError(`${name} must be an object`);
      }
      mongoOptions[name] = values[0];
      break;
    case 'any':
      mongoOptions[name] = values[0];
      break;
    default: {
      if (!transform) {
        throw new MongoParseError('Descriptors missing a type must define a transform');
      }
      const transformValue = transform({ name, options: mongoOptions, values });
      mongoOptions[name] = transformValue;
      break;
    }
  }
}

interface OptionDescriptor {

View on GitHub (pinned to dce7939f86)