{"record":{"id":"975536938e673d6d","repo":"apache/beam","slug":"position-to-be-claimed-cannot-be-smaller-than-the-start","errorCode":null,"errorMessage":"Position to be claimed cannot be smaller than the start position of the range. Tried to claim position %r for the range [%r, %r)","messagePattern":"Position to be claimed cannot be smaller than the start position of the range\\. Tried to claim position %r for the range \\[%r, %r\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/restriction_trackers.py","lineNumber":127,"sourceCode":"    return RestrictionProgress(fraction=fraction)\n\n  def start_position(self):\n    return self._range.start\n\n  def stop_position(self):\n    return self._range.stop\n\n  def try_claim(self, position):\n    if (self._last_claim_attempt is not None and\n        position <= self._last_claim_attempt):\n      raise ValueError(\n          'Positions claimed should strictly increase. Trying to claim '\n          'position %d while last claim attempt was %d.' %\n          (position, self._last_claim_attempt))\n\n    self._last_claim_attempt = position\n    if position < self._range.start:\n      raise ValueError(\n          'Position to be claimed cannot be smaller than the start position '\n          'of the range. Tried to claim position %r for the range [%r, %r)' %\n          (position, self._range.start, self._range.stop))\n\n    if self._range.start <= position < self._range.stop:\n      self._current_position = position\n      return True\n\n    return False\n\n  def try_split(self, fraction_of_remainder):\n    if not self._checkpointed:\n      if self._last_claim_attempt is None:\n        cur = self._range.start - 1\n      else:\n        cur = self._last_claim_attempt\n      split_point = (\n          cur + int(max(1, (self._range.stop - cur) * fraction_of_remainder)))","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/restriction_trackers.py#L109-L145","documentation":"OffsetRestrictionTracker.try_claim() rejects positions below the start of the restriction range. Beam raises this ValueError because the tracker can only acknowledge claims inside [start, stop); claiming before start would violate the restriction contract established at construction.","triggerScenarios":"Calling try_claim(position) where position < restriction.start, e.g. iterating a file from byte 0 while the restriction was split to start at byte 1000.","commonSituations":"Custom splittable DoFns that ignore the restriction's start when iterating (always starting from zero), or reusing a loop variable initialized outside the range after splitting.","solutions":["Initialize the iteration cursor from restriction.start() (or tracker.try_split results) instead of 0","Clamp or skip positions below range.start before claiming","Check for off-by-one errors where a split boundary was applied twice","If work before start is needed, request a restriction that includes it rather than claiming outside"],"exampleFix":"// before\nposition = 0\nwhile tracker.try_claim(position): ...\n// after\nposition = restriction.start()\nwhile tracker.try_claim(position): ...","handlingStrategy":"validation","validationCode":"def safe_claim(tracker, position):\n    start = tracker.current_restriction().start\n    if position < start:\n        position = start\n    return tracker.try_claim(position)","typeGuard":null,"tryCatchPattern":"try:\n    tracker.try_claim(position)\nexcept ValueError as e:\n    logger.error('Claim below restriction start: %s', e)","preventionTips":["Initialize iteration from restriction.start(), never 0","Respect split boundaries returned by try_split","Test SDFs after splitting to ensure cursors honor new starts"],"tags":["apache-beam","python","splittable-dofn"],"backgroundTag":"argument-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"}