{"record":{"id":"1e08f86b4b5a0d1d","repo":"apache/beam","slug":"invalid-incremental-inc-value-must-be-within-s-s","errorCode":null,"errorMessage":"invalid incremental, inc value must be within [%s, %s)","messagePattern":"invalid incremental, inc value must be within \\[(.+?), (.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/mongodbio.py","lineNumber":651,"sourceCode":"  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\n    Args:\n      _id: The `_id` to change.\n      inc(int): The incremental int value to be added to `_id`.\n\n    Returns:\n        `_id` incremented by `inc` value\n    \"\"\"\n    id_number = _ObjectIdHelper.id_to_int(_id)\n    new_number = id_number + inc\n    if new_number < 0 or new_number >= (1 << 96):\n      raise ValueError(\n          \"invalid incremental, inc value must be within [\"\n          \"%s, %s)\" % (0 - id_number, 1 << 96 - id_number))\n    return _ObjectIdHelper.int_to_id(new_number)\n\n\nclass WriteToMongoDB(PTransform):\n  \"\"\"WriteToMongoDB is a ``PTransform`` that writes a ``PCollection`` of\n  mongodb document to the configured MongoDB server.\n\n  In order to make the document writes idempotent so that the bundles are\n  retry-able without creating duplicates, the PTransform added 2 transformations\n  before final write stage:\n  a ``GenerateId`` transform and a ``Reshuffle`` transform.::\n\n                  -----------------------------------------------\n    Pipeline -->  |GenerateId --> Reshuffle --> WriteToMongoSink|\n                  -----------------------------------------------\n                                  (WriteToMongoDB)","sourceCodeStart":633,"sourceCodeEnd":669,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/mongodbio.py#L633-L669","documentation":"_ObjectIdHelper.increment_id adds inc to the integer form of an ObjectId and requires the result to remain a valid 96-bit value: 0 <= id + inc < 2**96. Violating that raises ValueError('invalid incremental, inc value must be within [-id_number, 2**96 - id_number)'). Note the message itself computes the upper bound with an operator-precedence bug (1 << 96 - id_number), so the displayed upper bound can be misleading — the actual check uses new_number >= (1 << 96).","triggerScenarios":"Calling _ObjectIdHelper.increment_id(_id, inc) where inc is negative with |inc| > id_number (underflow below 0) or so large that id_number + inc reaches 2**96 (overflow).","commonSituations":"Pagination/synthetic id generation that keeps incrementing past the maximum; passing a negative step larger than the current id; using increment sizes intended for 64-bit counters on a 96-bit ObjectId.","solutions":["Ensure 0 <= id_to_int(_id) + inc < 2**96 before calling; clamp or wrap inc accordingly.","If you need a negative shift, verify id_number >= -inc first.","Reset to a fresh base ObjectId when increments approach the 96-bit limit.","Compute the step as inc = target_number - id_to_int(_id) from a valid target id."],"exampleFix":"// before\nnext_id = _ObjectIdHelper.increment_id(_id, -10**30)\n// after\nn = _ObjectIdHelper.id_to_int(_id)\ninc = max(-n, -10**30)  # clamp so result stays >= 0\nnext_id = _ObjectIdHelper.increment_id(_id, inc)","handlingStrategy":"validation","validationCode":"n = _ObjectIdHelper.id_to_int(_id)\nif not (0 <= n + inc < (1 << 96)):\n    raise ValueError('inc would push id out of 96-bit range')","typeGuard":"def can_increment(_id, inc) -> bool:\n    n = _ObjectIdHelper.id_to_int(_id)\n    return 0 <= n + inc < (1 << 96)","tryCatchPattern":"try:\n    new_id = _ObjectIdHelper.increment_id(_id, inc)\nexcept ValueError:\n    new_id = _ObjectIdHelper.int_to_id((n + inc) % (1 << 96))  # wrap","preventionTips":["Clamp inc so the result stays within [0, 2**96).","Reset to a fresh base ObjectId near the limit.","Beware the error message's precedence bug — trust the actual check, not the printed bound."],"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-14T11:17:12.474Z"}