{"record":{"id":"ed638d2b774f942f","repo":"apache/beam","slug":"number-value-must-be-within-0-s","errorCode":null,"errorMessage":"number value must be within [0, %s)","messagePattern":"number value must be within \\[0, (.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/mongodbio.py","lineNumber":622,"sourceCode":"\n    # converts object id binary to integer\n    # id object is bytes type with size of 12\n    ints = struct.unpack(\">III\", _id.binary)\n    return (ints[0] << 64) + (ints[1] << 32) + ints[2]\n\n  @classmethod\n  def int_to_id(cls, number):\n    \"\"\"\n    Args:\n      number(int): The integer value to be used to convert to ObjectId.\n\n    Returns: The ObjectId that has the 12 bytes binary converted from the\n      integer value.\n    \"\"\"\n    # converts integer value to object id. Int value should be less than\n    # (2 ^ 96) so it can be convert to 12 bytes required by object id.\n    if number < 0 or number >= (1 << 96):\n      raise ValueError(\"number value must be within [0, %s)\" % (1 << 96))\n    ints = [\n        (number & 0xFFFFFFFF0000000000000000) >> 64,\n        (number & 0x00000000FFFFFFFF00000000) >> 32,\n        number & 0x0000000000000000FFFFFFFF,\n    ]\n\n    number_bytes = struct.pack(\">III\", *ints)\n    return ObjectId(number_bytes)\n\n  @classmethod\n  def increment_id(\n      cls,\n      _id: ObjectId,\n      inc: int,\n  ) -> ObjectId:\n    \"\"\"\n    Increment object_id binary value by inc value and return new object id.\n","sourceCodeStart":604,"sourceCodeEnd":640,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/mongodbio.py#L604-L640","documentation":"_ObjectIdHelper.int_to_id converts a 96-bit integer into a 12-byte MongoDB ObjectId. Because an ObjectId holds only 12 bytes, values must satisfy 0 <= number < 2**96; anything outside raises ValueError('number value must be within [0, 2**96)').","triggerScenarios":"Calling _ObjectIdHelper.int_to_id with a negative number, or a number >= 79228162514264337593543950335 (2**96) — e.g. after repeatedly incrementing an id, or converting a random int without masking to 96 bits.","commonSituations":"Generating synthetic _id values by integer arithmetic that overflows 96 bits; computing ids from hashes/uuids wider than 96 bits; incrementing beyond the max id during pagination loops.","solutions":["Mask the value into range before converting: number % (1 << 96).","Clamp negative values to 0 and validate 0 <= number < 2**96 before calling.","Derive the int from a real 12-byte ObjectId via id_to_int instead of an arbitrary wide integer.","For very large counters, switch to lexicographic string positions rather than int-to-ObjectId conversion."],"exampleFix":"// before\noid = _ObjectIdHelper.int_to_id(hash(value))\n// after\nn = hash(value) % (1 << 96)\noid = _ObjectIdHelper.int_to_id(n)","handlingStrategy":"validation","validationCode":"if not (0 <= number < (1 << 96)):\n    raise ValueError('number out of ObjectId range')","typeGuard":"def fits_object_id(n: int) -> bool:\n    return isinstance(n, int) and 0 <= n < (1 << 96)","tryCatchPattern":"try:\n    oid = _ObjectIdHelper.int_to_id(number)\nexcept ValueError:\n    oid = _ObjectIdHelper.int_to_id(number % (1 << 96))","preventionTips":["Mask wide integers with % (1 << 96) before converting.","Derive ints from real ObjectIds via id_to_int.","Guard increments with range checks before converting."],"tags":["mongodb","objectid","value-out-of-range"],"backgroundTag":"value-out-of-range","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}