{"record":{"id":"b40e8c96b7f8eed1","repo":"Automattic/mongoose","slug":"mongoose-only-supports-bigints-between-9223372036","errorCode":null,"errorMessage":"Mongoose only supports BigInts between -9223372036854775808 and 9223372036854775807 because MongoDB does not support arbitrary precision integers","messagePattern":"Mongoose only supports BigInts between -9223372036854775808 and 9223372036854775807 because MongoDB does not support arbitrary precision integers","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/cast/bigint.js","lineNumber":28,"sourceCode":" * @return {bigint|null|undefined}\n * @throws {Error} if `value` is not one of the allowed values\n * @api private\n */\n\nconst MAX_BIGINT = 9223372036854775807n;\nconst MIN_BIGINT = -9223372036854775808n;\nconst ERROR_MESSAGE = `Mongoose only supports BigInts between ${MIN_BIGINT} and ${MAX_BIGINT} because MongoDB does not support arbitrary precision integers`;\n\nmodule.exports = function castBigInt(val) {\n  if (val == null) {\n    return val;\n  }\n  if (val === '') {\n    return null;\n  }\n  if (typeof val === 'bigint') {\n    if (val > MAX_BIGINT || val < MIN_BIGINT) {\n      throw new Error(ERROR_MESSAGE);\n    }\n    return val;\n  }\n\n  if (val instanceof Long) {\n    return val.toBigInt();\n  }\n\n  if (typeof val === 'string' || typeof val === 'number') {\n    val = BigInt(val);\n    if (val > MAX_BIGINT || val < MIN_BIGINT) {\n      throw new Error(ERROR_MESSAGE);\n    }\n    return val;\n  }\n\n  throw new Error(`Cannot convert value to BigInt: \"${val}\"`);\n};","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/cast/bigint.js#L10-L46","documentation":"mongoose maps its BigInt type onto MongoDB's 64-bit int64, so castBigInt rejects values outside [-2^63, 2^63-1] -- MongoDB has no arbitrary-precision integer, so a wider value could not round-trip. This throw site is the bounds check for values that are already bigint when they reach the caster.","triggerScenarios":"doc.big = 99999999999999999999n followed by save(); Model.find({ big: 12345678901234567890n }); any bigint literal or computed bigint beyond 9223372036854775807 assigned to a Schema.Types.BigInt path.","commonSituations":"Snowflake IDs, nanosecond timestamps, or ledger/satoshi-precision amounts that overflow int64; bigints produced by BigInt(input) of huge user numbers; migrations from Number paths where stored values already exceeded int64.","solutions":["Keep values within int64 range: -9223372036854775808..9223372036854775807","Switch the path to Schema.Types.Decimal128 for higher precision","Store as String with custom getters/setters when exact display matters more than arithmetic"],"exampleFix":"// before\nconst schema = new Schema({ big: Schema.Types.BigInt });\ndoc.big = 99999999999999999999n; // > 2^63 - 1\n\n// after\nconst schema = new Schema({ big: Schema.Types.Decimal128 });\ndoc.big = Decimal128.fromString('99999999999999999999');","handlingStrategy":"type-guard","validationCode":"const MIN64 = -(2n ** 63n);\nconst MAX64 = (2n ** 63n) - 1n;\nfunction toSafeBigInt(v) {\n  const b = typeof v === 'bigint' ? v : BigInt(v);\n  if (b < MIN64 || b > MAX64) {\n    throw new RangeError('Value exceeds MongoDB int64 range');\n  }\n  return b;\n}\ndoc.big = toSafeBigInt(input);","typeGuard":"function isInt64BigInt(v) {\n  return typeof v === 'bigint' && v >= -(2n ** 63n) && v <= (2n ** 63n) - 1n;\n}","tryCatchPattern":"try {\n  await doc.save();\n} catch (err) {\n  if (err.message.includes('Mongoose only supports BigInts between')) {\n    // the assigned value overflows int64; store as Decimal128/String instead\n  }\n  throw err;\n}","preventionTips":["Check magnitudes at ingestion when IDs are generated externally (snowflakes, ULID-derived numbers)","Prefer Decimal128 for financial amounts","Unit-test boundary values 9223372036854775807n / -9223372036854775808n on BigInt paths"],"tags":["mongoose","bigint","int64","cast"],"backgroundTag":"bigint-overflow","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}