apache/beam · error · ValueError

start_offset must be smaller than stop_offset. Received

Error message

start_offset must be smaller than stop_offset. Received %d and %d for start and stop offsets respectively

What it means

_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.

Solutions

1. Ensure start_offset is strictly less than stop_offset before constructing the source
2. Skip building the source entirely when the computed range is empty
3. Check argument order — start_offset comes before stop_offset

Example fix

// before
start, stop = size, size
src = _FileBasedSource(path, start, stop)
// after
if start < stop:
  src = _FileBasedSource(path, start, stop)
else:
  return  # empty range: nothing to read

if start_offset >= stop_offset:
    raise ValueError(f'empty range: start {start_offset} >= stop {stop_offset}')

def is_valid_range(start: int, stop: int) -> bool:
    return isinstance(start, int) and isinstance(stop, int) and start < stop

try:
    src = _FileBasedSource(path, start, stop)
except ValueError as e:
    if 'start_offset must be smaller than stop_offset' in str(e):
        logging.info('Skipping empty range [%d, %d)', start, stop)
    else:
        raise

When it happens

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

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

Related errors

• start_offset must be a number. Received: %r
• stop_offset must be a number. Received: %r
• Append to stream failed with invalid offset of
• ApproximateUnique needs a size >= 16 for an error <= 0.50…
• ApproximateUnique needs an estimation error between 0.01…

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/69ad0b073715101f. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/io/filebasedsource.py:259

class _SingleFileSource(iobase.BoundedSource):
  """Denotes a source for a specific file type."""
  def __init__(
      self,
      file_based_source,
      file_name,
      start_offset,
      stop_offset,
      min_bundle_size=0,
      splittable=True):
    if not isinstance(start_offset, int):
      raise TypeError(
          'start_offset must be a number. Received: %r' % start_offset)
    if stop_offset != range_trackers.OffsetRangeTracker.OFFSET_INFINITY:
      if not isinstance(stop_offset, int):
        raise TypeError(
            'stop_offset must be a number. Received: %r' % stop_offset)
      if start_offset >= stop_offset:
        raise ValueError(
            'start_offset must be smaller than stop_offset. Received %d and %d '
            'for start and stop offsets respectively' %
            (start_offset, stop_offset))

    self._file_name = file_name
    self._is_gcs_file = file_name.startswith('gs://') if file_name else False
    self._start_offset = start_offset
    self._stop_offset = stop_offset
    self._min_bundle_size = min_bundle_size
    self._file_based_source = file_based_source
    self._splittable = splittable

  def split(self, desired_bundle_size, start_offset=None, stop_offset=None):
    if start_offset is None:
      start_offset = self._start_offset
    if stop_offset is None:
      stop_offset = self._stop_offset

View on GitHub (pinned to 12126d8942)