mongodb/node-mongodb-native · error · MongoAPIError

Must request either bigint or Long for int64 deserialization

Error message

Must request either bigint or Long for int64 deserialization

What it means

BSON int64 deserialization mode conflict. useBigInt64 asks the driver to materialize 64-bit ints as JS bigint, but promoteLongs=false tells it NOT to return Long objects either. Together they leave no valid representation for int64, so the driver refuses to construct options. The same message is reused for the promoteValues=false case at line 253.

Solutions

1. Drop promoteLongs: false (allow it to default to true) when using useBigInt64.
2. Or remove useBigInt64 if you intentionally want non-Long promotion.

Example fix

// before
new MongoClient(uri, { useBigInt64: true, promoteLongs: false });
// after
new MongoClient(uri, { useBigInt64: true });

function assertBigIntOptions(opts: { useBigInt64?: boolean; promoteLongs?: boolean; promoteValues?: boolean }) {
  if (opts.useBigInt64 && typeof opts.promoteLongs === 'boolean' && !opts.promoteLongs) {
    throw new Error('useBigInt64 requires promoteLongs !== false');
  }
}

When it happens

Trigger: Calling new MongoClient(uri, { useBigInt64: true, promoteLongs: false }). The check runs at the top of parseOptions before any URI parsing.

Common situations: Enabling useBigInt64 for native bigint support while keeping an older config that set promoteLongs: false to force string/number promotion.

Related errors

• input cluster time "clusterTime" property must be a valid…
• input cluster time must be an object
• input cluster time must have a valid "signature" property…
• not supported
• Properties "causalConsistency" and "snapshot" are mutually…

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

Appendix: source

Thrown at src/connection_string.ts:249

  }
  override delete(k: string): boolean {
    return super.delete(k.toLowerCase());
  }
}

export function parseOptions(
  uri: string,
  mongoClient: MongoClient | MongoClientOptions | undefined = undefined,
  options: MongoClientOptions = {}
): MongoOptions {
  if (mongoClient != null && !(mongoClient instanceof MongoClient)) {
    options = mongoClient;
    mongoClient = undefined;
  }

  // validate BSONOptions
  if (options.useBigInt64 && typeof options.promoteLongs === 'boolean' && !options.promoteLongs) {
    throw new MongoAPIError('Must request either bigint or Long for int64 deserialization');
  }

  if (options.useBigInt64 && typeof options.promoteValues === 'boolean' && !options.promoteValues) {
    throw new MongoAPIError('Must request either bigint or Long for int64 deserialization');
  }

  const url = new ConnectionString(uri);
  const { hosts, isSRV } = url;

  const mongoOptions = Object.create(null);

  mongoOptions.hosts = isSRV ? [] : hosts.map(HostAddress.fromString);

  const urlOptions = new CaseInsensitiveMap<unknown[]>();

  if (url.pathname !== '/' && url.pathname !== '') {
    const dbName = decodeURIComponent(
      url.pathname[0] === '/' ? url.pathname.slice(1) : url.pathname

View on GitHub (pinned to dce7939f86)