{"id":"72afc75ae54395cb","repo":"mongodb/node-mongodb-native","slug":"must-request-either-bigint-or-long-for-int64-deser","errorCode":null,"errorMessage":"Must request either bigint or Long for int64 deserialization","messagePattern":"Must request either bigint or Long for int64 deserialization","errorType":"exception","errorClass":"MongoAPIError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":249,"sourceCode":"  }\n  override delete(k: string): boolean {\n    return super.delete(k.toLowerCase());\n  }\n}\n\nexport function parseOptions(\n  uri: string,\n  mongoClient: MongoClient | MongoClientOptions | undefined = undefined,\n  options: MongoClientOptions = {}\n): MongoOptions {\n  if (mongoClient != null && !(mongoClient instanceof MongoClient)) {\n    options = mongoClient;\n    mongoClient = undefined;\n  }\n\n  // validate BSONOptions\n  if (options.useBigInt64 && typeof options.promoteLongs === 'boolean' && !options.promoteLongs) {\n    throw new MongoAPIError('Must request either bigint or Long for int64 deserialization');\n  }\n\n  if (options.useBigInt64 && typeof options.promoteValues === 'boolean' && !options.promoteValues) {\n    throw new MongoAPIError('Must request either bigint or Long for int64 deserialization');\n  }\n\n  const url = new ConnectionString(uri);\n  const { hosts, isSRV } = url;\n\n  const mongoOptions = Object.create(null);\n\n  mongoOptions.hosts = isSRV ? [] : hosts.map(HostAddress.fromString);\n\n  const urlOptions = new CaseInsensitiveMap<unknown[]>();\n\n  if (url.pathname !== '/' && url.pathname !== '') {\n    const dbName = decodeURIComponent(\n      url.pathname[0] === '/' ? url.pathname.slice(1) : url.pathname","sourceCodeStart":231,"sourceCodeEnd":267,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/connection_string.ts#L231-L267","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove promoteLongs:false (or set it to true) when enabling useBigInt64.","If you want numbers, disable useBigInt64 instead and keep promoteLongs as desired.","Centralize BSON option selection in one config module to prevent conflicts.","Add an assertion in your config loader that useBigInt64 implies promoteLongs !== false."],"exampleFix":"// before\nnew MongoClient(uri, { useBigInt64: true, promoteLongs: false });\n// after\nnew MongoClient(uri, { useBigInt64: true }); // promoteLongs defaults to true","handlingStrategy":"validation","validationCode":"function reconcileBsonOptions<T extends { useBigInt64?: boolean; promoteLongs?: boolean }>(opts: T): T {\n  if (opts.useBigInt64 && opts.promoteLongs === false) {\n    throw new Error('useBigInt64 requires promoteLongs !== false');\n  }\n  return opts;\n}","typeGuard":"const hasConflictingLongs = (o: { useBigInt64?: boolean; promoteLongs?: boolean }): boolean =>\n  o.useBigInt64 === true && o.promoteLongs === false;","tryCatchPattern":"try {\n  const client = new MongoClient(uri, opts);\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoAPIError && /bigint or Long for int64/.test(e.message)) {\n    const { promoteLongs, ...rest } = opts;\n    return new MongoClient(uri, rest); // drop the conflicting flag\n  }\n  throw e;\n}","preventionTips":["Centralize BSON options in one config module.","When enabling useBigInt64, audit existing promoteLongs/promoteValues settings.","Prefer bigint for new code; do not mix with promotion-disabling flags."],"tags":["connection-string","bson","config","int64"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}