Automattic/mongoose · error · Error

Mongoose only supports BigInts between -9223372036854775808

Error message

Mongoose only supports BigInts between -9223372036854775808 and 9223372036854775807 because MongoDB does not support arbitrary precision integers

What it means

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.

Source

Thrown at lib/cast/bigint.js:28

 * @return {bigint|null|undefined}
 * @throws {Error} if `value` is not one of the allowed values
 * @api private
 */

const MAX_BIGINT = 9223372036854775807n;
const MIN_BIGINT = -9223372036854775808n;
const ERROR_MESSAGE = `Mongoose only supports BigInts between ${MIN_BIGINT} and ${MAX_BIGINT} because MongoDB does not support arbitrary precision integers`;

module.exports = function castBigInt(val) {
  if (val == null) {
    return val;
  }
  if (val === '') {
    return null;
  }
  if (typeof val === 'bigint') {
    if (val > MAX_BIGINT || val < MIN_BIGINT) {
      throw new Error(ERROR_MESSAGE);
    }
    return val;
  }

  if (val instanceof Long) {
    return val.toBigInt();
  }

  if (typeof val === 'string' || typeof val === 'number') {
    val = BigInt(val);
    if (val > MAX_BIGINT || val < MIN_BIGINT) {
      throw new Error(ERROR_MESSAGE);
    }
    return val;
  }

  throw new Error(`Cannot convert value to BigInt: "${val}"`);
};

View on GitHub (pinned to 49cdab0136)

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

Example fix

// before
const schema = new Schema({ big: Schema.Types.BigInt });
doc.big = 99999999999999999999n; // > 2^63 - 1

// after
const schema = new Schema({ big: Schema.Types.Decimal128 });
doc.big = Decimal128.fromString('99999999999999999999');

Defensive patterns

Strategy: type-guard

Validate before calling

const MIN64 = -(2n ** 63n);
const MAX64 = (2n ** 63n) - 1n;
function toSafeBigInt(v) {
  const b = typeof v === 'bigint' ? v : BigInt(v);
  if (b < MIN64 || b > MAX64) {
    throw new RangeError('Value exceeds MongoDB int64 range');
  }
  return b;
}
doc.big = toSafeBigInt(input);

Type guard

function isInt64BigInt(v) {
  return typeof v === 'bigint' && v >= -(2n ** 63n) && v <= (2n ** 63n) - 1n;
}

Try / catch

try {
  await doc.save();
} catch (err) {
  if (err.message.includes('Mongoose only supports BigInts between')) {
    // the assigned value overflows int64; store as Decimal128/String instead
  }
  throw err;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of Automattic/mongoose@49cdab0136 (2026-08-21). Data as JSON: /api/errors/b40e8c96b7f8eed1. Report an issue: GitHub.