apache/beam · error · ValueError

Start offset must be not be larger than the stop offset…

Error message

Start offset must be not be larger than the stop offset. Received %d and %d respectively.

What it means

OffsetRange.__init__ validates that the start offset does not exceed the stop offset when constructing a bounded range for splittable DoFn sources. Apache Beam throws this ValueError immediately at construction because a reversed range is meaningless: it would represent a negative amount of work and break offset-based splitting and progress tracking.

Solutions

Check the values passed to OffsetRange and ensure stop >= start
Swap the arguments if they were passed in the wrong order
Clamp or validate computed lengths before constructing (e.g. guard length >= 0)
If the range is genuinely empty, pass start == stop, which is allowed

Example fix

// before
range = OffsetRange(end_offset, start_offset)
// after
assert start_offset <= end_offset
range = OffsetRange(start_offset, end_offset)

Defensive patterns

Strategy: validation

Validate before calling

def safe_offset_range(start, stop):
    if start > stop:
        raise ValueError(f'invalid range: start={start} > stop={stop}')
    return OffsetRange(start, stop)

Try / catch

try:
    rng = OffsetRange(start, stop)
except ValueError as e:
    logger.error('Invalid OffsetRange: %s', e)
    rng = None

Prevention

Always assert start <= stop before constructing OffsetRange
Derive stop from start + non-negative length only
Add unit tests for boundary cases (start == stop)

When it happens

Trigger: Calling OffsetRange(start, stop) with start > stop, e.g. OffsetRange(100, 0) or computing offsets from user data where a slice end is smaller than the slice beginning.

Common situations: Reading byte/row ranges computed from file sizes or user-specified windows where the end was calculated as start + length with a negative length, or swapping argument order.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/io/restriction_trackers.py:29

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

"""`iobase.RestrictionTracker` implementations provided with Apache Beam."""
# pytype: skip-file

from apache_beam.io.iobase import RestrictionProgress
from apache_beam.io.iobase import RestrictionTracker
from apache_beam.io.range_trackers import OffsetRangeTracker


class OffsetRange(object):
  def __init__(self, start, stop):
    if start > stop:
      raise ValueError(
          'Start offset must be not be larger than the stop offset. '
          'Received %d and %d respectively.' % (start, stop))
    self.start = start
    self.stop = stop

  def __eq__(self, other):
    if not isinstance(other, OffsetRange):
      return False

    return self.start == other.start and self.stop == other.stop

  def __hash__(self):
    return hash((type(self), self.start, self.stop))

  def __repr__(self):
    return 'OffsetRange(start=%s, stop=%s)' % (self.start, self.stop)

  def split(self, desired_num_offsets_per_split, min_num_offsets_per_split=1):

View on GitHub (pinned to 12126d8942)