{"record":{"id":"69ad0b073715101f","repo":"apache/beam","slug":"start-offset-must-be-smaller-than-stop-offset-received-d-and","errorCode":null,"errorMessage":"start_offset must be smaller than stop_offset. Received %d and %d for start and stop offsets respectively","messagePattern":"start_offset must be smaller than stop_offset\\. Received (.+?) and (.+?) for start and stop offsets respectively","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/filebasedsource.py","lineNumber":259,"sourceCode":"class _SingleFileSource(iobase.BoundedSource):\n  \"\"\"Denotes a source for a specific file type.\"\"\"\n  def __init__(\n      self,\n      file_based_source,\n      file_name,\n      start_offset,\n      stop_offset,\n      min_bundle_size=0,\n      splittable=True):\n    if not isinstance(start_offset, int):\n      raise TypeError(\n          'start_offset must be a number. Received: %r' % start_offset)\n    if stop_offset != range_trackers.OffsetRangeTracker.OFFSET_INFINITY:\n      if not isinstance(stop_offset, int):\n        raise TypeError(\n            'stop_offset must be a number. Received: %r' % stop_offset)\n      if start_offset >= stop_offset:\n        raise ValueError(\n            'start_offset must be smaller than stop_offset. Received %d and %d '\n            'for start and stop offsets respectively' %\n            (start_offset, stop_offset))\n\n    self._file_name = file_name\n    self._is_gcs_file = file_name.startswith('gs://') if file_name else False\n    self._start_offset = start_offset\n    self._stop_offset = stop_offset\n    self._min_bundle_size = min_bundle_size\n    self._file_based_source = file_based_source\n    self._splittable = splittable\n\n  def split(self, desired_bundle_size, start_offset=None, stop_offset=None):\n    if start_offset is None:\n      start_offset = self._start_offset\n    if stop_offset is None:\n      stop_offset = self._stop_offset\n","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/filebasedsource.py#L241-L277","documentation":"_FileBasedSource.__init__ enforces start_offset < stop_offset (when stop_offset is not OFFSET_INFINITY) and raises ValueError otherwise. A zero-width or inverted offset range would produce no readable region and break RangeTracker assumptions, so it is rejected eagerly.","triggerScenarios":"Constructing a _FileBasedSource where start_offset >= stop_offset, e.g. both set to the same byte position, swapped arguments, or a start computed as file_size while stop is file_size too.","commonSituations":"Swapping start/stop parameter order in a custom constructor call; computing ranges per-bundle where an empty slice is passed as-is instead of being skipped.","solutions":["Ensure start_offset is strictly less than stop_offset before constructing the source","Skip building the source entirely when the computed range is empty","Check argument order — start_offset comes before stop_offset"],"exampleFix":"// before\nstart, stop = size, size\nsrc = _FileBasedSource(path, start, stop)\n// after\nif start < stop:\n  src = _FileBasedSource(path, start, stop)\nelse:\n  return  # empty range: nothing to read","handlingStrategy":"validation","validationCode":"if start_offset >= stop_offset:\n    raise ValueError(f'empty range: start {start_offset} >= stop {stop_offset}')","typeGuard":"def is_valid_range(start: int, stop: int) -> bool:\n    return isinstance(start, int) and isinstance(stop, int) and start < stop","tryCatchPattern":"try:\n    src = _FileBasedSource(path, start, stop)\nexcept ValueError as e:\n    if 'start_offset must be smaller than stop_offset' in str(e):\n        logging.info('Skipping empty range [%d, %d)', start, stop)\n    else:\n        raise","preventionTips":["Skip constructing sources for empty computed ranges","Double-check start/stop argument order in custom constructor calls","Add assertions on range sanity where offsets are computed per bundle"],"tags":["offset","value-out-of-range","constructor"],"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-20T03:17:13.778Z"}