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

Thrown by parseOptions() when useBigInt64 is true AND promoteLongs is explicitly set to false. With useBigInt64, 64-bit integers deserialize as JS bigint; setting promoteLongs=false (which would deserialize them as numbers, risking precision loss) contradicts that contract, so the driver rejects the combination as a MongoAPIError at client construction.

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 3366c21a63)

Solutions

1. Remove promoteLongs:false (or set it to true) when enabling useBigInt64.
2. If you want numbers, disable useBigInt64 instead and keep promoteLongs as desired.
3. Centralize BSON option selection in one config module to prevent conflicts.
4. Add an assertion in your config loader that useBigInt64 implies promoteLongs !== false.

Example fix

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

function reconcileBsonOptions<T extends { useBigInt64?: boolean; promoteLongs?: boolean }>(opts: T): T {
  if (opts.useBigInt64 && opts.promoteLongs === false) {
    throw new Error('useBigInt64 requires promoteLongs !== false');
  }
  return opts;
}

const hasConflictingLongs = (o: { useBigInt64?: boolean; promoteLongs?: boolean }): boolean =>
  o.useBigInt64 === true && o.promoteLongs === false;

try {
  const client = new MongoClient(uri, opts);
  await client.connect();
} catch (e) {
  if (e instanceof MongoAPIError && /bigint or Long for int64/.test(e.message)) {
    const { promoteLongs, ...rest } = opts;
    return new MongoClient(uri, rest); // drop the conflicting flag
  }
  throw e;
}

When it happens

Trigger: Passing { useBigInt64: true, promoteLongs: false } to new MongoClient; merging a base config that sets promoteLongs:false with a feature flag enabling useBigInt64; copy-pasting options from a codebase that disabled promoteLongs for safety.

Common situations: Enabling bigint support for Int64 fidelity while an existing config still disables promoteLongs; upgrading the driver and turning on useBigInt64 without auditing existing promoteLongs settings; mixing options across modules.

Related errors

• Option "srvHost" must not be empty
• Multiple text records not allowed
• Text record may only set any of: ${VALID_TXT_RECORDS.join(',
• Cannot have empty URI params in DNS TXT Record
• Cannot combine replicaSet option with srvMaxHosts

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